Farmbrite MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description reinforces this with 'Adds a record each time', making it explicit that repeat calls create duplicate records rather than upserting — a genuinely useful clarification. It does not mention permission requirements or what happens if no measurement field is supplied.

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 line, front-loaded with the WRITE classification followed by resource, accepted fields, append semantics, and endpoint. No filler; the endpoint at the end is a small but harmless identifier aid.

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 seven parameters, no output schema and 43% schema coverage, the description covers the field vocabulary but leaves gaps an agent would want: unit expectations for weight/height/temp, whether 'date' defaults to today, and what comes back after a successful write.

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 43%, but the description compensates partially by naming the five measurement fields, which maps to fec, temp, height, weight and condition_score. The 'date' parameter remains undocumented in both schema and description (no format or default), and nothing says at least one measurement value must be provided.

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 ('record a measurement for one animal') and enumerates exactly which measurement kinds are accepted (weight, height, temperature, condition score, fecal egg count). This clearly separates it from farmbrite_create_animal and the read-side farmbrite_list_animal_measurements.

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?

'WRITE:' and 'Adds a record each time' imply this is for appending new measurements to an existing animal rather than correcting one. However, there is no explicit when-to-use guidance, no statement that the animal must already exist, and no pointer to farmbrite_list_animal_measurements for verification or to farmbrite_update_animal for corrections.

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 idempotentHint=false and destructiveHint=false, so the description's real contribution is the consequence of that flag — 'repeating adds again' — which is the practical detail an agent needs before retrying. It also discloses the underlying PUT endpoint. It stops short of permissions or error behavior, but that is minor given annotation coverage.

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

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

Four short clauses, front-loaded with the WRITE marker and the not-idempotent warning placed before the id-discovery pointers. No filler sentences.

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

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

The core write path (ids, quantity direction, non-idempotency, endpoint) is covered, but with 8 parameters and no output schema an agent still has to guess what the undocumented fields (date, source, lot_number, description) mean and whether they matter. Adequate but with clear gaps for a mutation tool.

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

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

Schema coverage is only 50%, and the description compensates for just part of the gap: it clarifies that bin_id is optional within a warehouse and that the quantity must add (positive). Half the parameters — date, source, lot_number, description — get no mention in either the description text or the schema, so the coverage gap remains.

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

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

States a concrete verb and resource ('add stock to an inventory item') plus the target location (warehouse, optional bin). The 'WRITE:' prefix and the sibling name farmbrite_remove_inventory make the direction of the operation unambiguous 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?

Explicitly tells the agent how to resolve the three required ids by naming farmbrite_list_inventory_types, farmbrite_get_inventory_locations and farmbrite_list_warehouses. It implies the contrast with removal ('Raises the quantity remaining') but never states when not to use it, e.g. that farmbrite_remove_inventory is the tool for decreases.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description adds useful context: duplicate calls create two animals, and group creation is gated on is_group=true with group_qty. One inaccuracy: it claims status is required, while the schema makes it optional with a default of 'Active' — a minor misstatement that could mislead.

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 operation type front-loaded, required-field note, duplicate warning, and endpoint. Nothing extraneous.

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 23-parameter mutation tool with no output schema and low schema coverage, the description leaves the majority of parameters unexplained and gives no guidance on relationships like death_date being tied to certain statuses. It is adequate for the core create action but not for calling the tool correctly with richer payloads.

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 23 parameters and only 30% schema coverage, the description should compensate but only explains type, is_group, group_qty, and status. Most parameters (name, breed, gender, weight, dates, parent ids, market/purchase fields, etc.) receive no meaning from either schema or 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 and resource ('add an animal ... to the herd') and distinguishes creation from the update/list siblings. The parenthetical group-creation case and the POST endpoint further pin down what the tool does.

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

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

It conveys when to use it implicitly (creating, not modifying, an animal) and warns that duplicate calls create duplicates, but it never names an alternative such as farmbrite_update_animal or farmbrite_list_animals for modification/lookup. The when-to-use context is implied rather than explicit.

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 genuinely non-obvious behavior beyond the annotations: no email/notification side effect is triggered on the contact, and duplicate calls create duplicate records (consistent with idempotentHint=false). It does not cover permission requirements, validation failures, or what the response returns, so it stops short of full 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?

Three short sentences plus an endpoint reference, each carrying distinct information (mutation type, valid subtypes, no notification side effect, duplicate behavior). Front-loaded and 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?

Behavioral traits and the write classification are covered, and annotations already declare the safety profile so return-format detail is optional. However, for a tool with 10 loosely documented, all-optional parameters and a nested address object, the description gives no guidance on what fields make a usable contact, which leaves an agent guessing at call construction.

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 10 parameters and only 10% schema description coverage, the description must carry the burden, and it barely does — the only parameter-related information is the 'Customer or Vendor' examples for the `type` field. Nine other fields (label, first_name, last_name, email, address nested object, etc.) and the question of a minimally valid create (zero required params) 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?

States a specific verb and resource ('create a contact') and enumerates the concrete subtypes it covers (customer, supplier, vendor), plus the underlying endpoint POST /contacts. The 'WRITE:' prefix and 'create' verb make it trivially distinguishable from siblings like list_contacts, get_contact, and update_contact.

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 rather than stated: 'Creating twice makes two contacts' warns against duplicate invocation, and 'Nothing is emailed or sent' sets expectations, but there is no explicit 'use this instead of X' routing to update_contact for existing records or to list_contacts for lookup. An agent can infer when to use it, but the guidance is not spelled out.

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

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

Adds a critical side effect beyond annotations: drawing from inventory lowers that inventory's quantity. It also reinforces append-only behavior ('adds a record each time'), consistent with non-idempotent/destructive annotations. Does not cover permissions or what happens if both feed type and inventory are supplied.

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

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

Three tightly packed sentences, front-loaded with the mutating nature and the core targeting, then the inventory alternative, then append semantics and endpoint. 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 an 11-parameter mutation with no output schema, it covers the essential decision space (parent targeting, amount source) and the key destructive consequence. Optional fields like cost, date, unit, and per_head are left entirely to the schema, which is acceptable but not complete.

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

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

The schema already documents type, amount, per_head, parent_id, inventory_id, and inventory_location_id, so much of the description's routing information is a synthesis of existing schema text. It does clarify the either/or relationship between feed type and inventory parameters, but says nothing about cost, date, unit, or description fields.

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 ('record a feeding for an animal or livestock group') and scopes it to the two parent types, making it distinguishable from list_feedings and other create_* siblings. The explicit WRITE prefix and endpoint reinforce exactly what the tool does.

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

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

Gives a clear usage decision: either name the feed type or supply inventory_id + inventory_location_id to draw from stock. This tells the agent which call pattern to choose, though it does not state when to avoid the tool or name an alternative (e.g., list_feedings for viewing).

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, idempotentHint=false, destructiveHint=false and openWorldHint=true; the description mainly restates the write/append nature ('Adds a record each time', 'WRITE:'). It adds the concrete POST route and parent-type scoping, but says nothing about permissions, validation failures, or what a partial/invalid unit does — a modest addition on an already-annotated 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?

Three short, front-loaded sentences — operation type, entity and required fields, then append behavior and route. Nothing is wasted and the most decision-relevant information comes first.

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

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

With nine parameters, 22% schema coverage, and no output schema, the description is too thin: it omits what the tool returns (harvest record id?) and leaves most optional fields undefined. Enough to identify the action, not enough to call it richly.

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?

Only about 22% of the nine parameters are documented in the schema, so the description must compensate, and it only covers qty/unit and the parent/parent_id pairing. It never explains the optional date, grade, price, description, or batch_number fields, leaving six of nine parameters without any semantic guidance.

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 (record), resource (harvest), and scope (for an animal OR crop planting), plus the underlying endpoint POST /{animals|crops}/{id}/harvests. The 'WRITE' prefix and 'Adds a record each time' make it unambiguously distinct from the sibling list_harvests read 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?

The description implies usage (create a new harvest entry with quantity and unit) and hints that repeats append rather than replace, but it never explicitly states when to choose this over farmbrite_list_harvests or any update path, nor any prerequisites such as needing harvested crops/animals to exist first. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds one genuine behavioral fact beyond them - notes cannot be deleted via this server - and reveals the endpoint shape, but says nothing about the response, required permissions, or duplicate-note behavior.

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

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

Two tight sentences, write marker front-loaded, permitted parent types and the non-deletion caveat each stated once 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 mutation tool with six parameters, no output schema and half the parameters undocumented, the description leaves real gaps: what the call returns (e.g., a new note id for later reference), and the semantics of date/category/keywords. It is adequate to invoke the tool but thin for a write 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 coverage is only 50%; date, category and keywords have no schema descriptions and the description compensates for none of them (no format, allowed values, or meaning). The prose parent list loosely maps to the enum, but the mapping is ambiguous (field vs plots, plant type vs plants) rather than clarifying.

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 ('add a note') and enumerates the supported parent types, matching the schema enum. The 'WRITE:' prefix separates it from the read counterpart farmbrite_list_notes, though the sibling is never 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 context is implied by the enumerated parent types, but there is no explicit guidance on when to use this versus farmbrite_list_notes or whether an existing note can/should be edited elsewhere. The only constraint given is that notes cannot be removed with this server.

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 past the annotations by disclosing defaults for status and payment_status, the memo/note visibility split, the back-office (is_admin) entry mode, and the non-idempotent consequence ('creating twice makes two orders'). It also honestly flags an unknown side effect (possible customer email or invoice generation) and hedges correctly rather than inventing behavior.

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

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

Front-loads the WRITE marker and the core action, then layers constraints in descending importance; almost every clause carries information. The nested parentheticals pack a lot into one dense paragraph, which makes it slightly harder to scan than strictly necessary.

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 16-parameter mutation with no output schema, the description covers the decisions that most affect correctness: defaults, disclosure risks, idempotency, and entry mode. It never indicates what a successful call returns (e.g., a created order id), which an agent needs since there is no output schema to fall back on.

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 31% across 16 parameters, so the description needs to carry more weight than it does. It does add real meaning for email, status, memo/note, and the line-items requirement, but leaves roughly ten parameters (due_date, order_date, tax_rate, contact_id, phone, payment_method, delivery_amount, discount_amount, first/last_name) without any guidance beyond their 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 ('create a sales order with line items') plus the endpoint (POST /orders) and the entry mode (back-office order via is_admin). The write framing and line-item scope distinguish it cleanly from the sibling get_order/update_order/list_orders tools without needing 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?

Gives explicit operational direction: use Draft unless the user asks otherwise, and only pass email when the user requests it. It does not name a sibling alternative or exclusion, so it falls short of full when/when-not routing, but the conditional guidance is clear and directly actionable.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds useful behavioral detail beyond annotations: creating twice makes two tasks, and assigning a user may trigger a notification based on account settings.

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 four short sentences, front-loaded with the write action and followed by the most relevant behavioral caveats. Every sentence adds useful information without repetition.

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

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

For a create tool with nine parameters, annotations, and no output schema, the description covers the action, optional relationships, notification side effect, and non-idempotency. It could mention what the response contains, but the core behavior is sufficiently described.

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 78%, with most meaningful parameters already documented in the schema. The description adds the optional linkage concept and notification implication for assigned_to_id, but does not add format, constraints, or semantics beyond what the schema largely 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?

The description uses a specific verb and resource: 'create a task.' It also clarifies optional linking to five entity types and signals this is a write operation, making it clearly distinct from get/update/list task 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 clear context for creating a new task and notes optional reference linking and assignment notification. It does not explicitly name update_task or list_tasks as alternatives, but the create-vs-update distinction is clear from the verb and WRITE label.

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, idempotentHint=false and destructiveHint=false, so the safety profile is covered; the description's duplication warning adds concrete consequence beyond the idempotentHint flag. It does not say what is returned (e.g., the new id), what happens with an invalid category or unknown ref_id, or whether failed validation partially writes.

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 fragments, front-loaded with the WRITE marker, with zero filler. The duplication caveat and endpoint are each one clause and both earn their 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 10-parameter mutation with no output schema, the definition covers the write semantics but omits the return value and required-field expectations a caller needs to chain on (e.g., retrieving the created transaction). Adequate given the annotations, but not 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 60% (date, amount, ref_id, vendor, category, ref_type documented), so the schema carries most of the burden and the description adds nothing about parameters. The four undocumented fields (type, keywords, description, check_number) get no compensating explanation, but type is self-evident from its enum.

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 plus resource and the domain object: 'record an income or expense transaction in the farm's books', with the endpoint POST /transactions. That cleanly separates it from the read siblings (list_transactions, get_transaction), 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?

'Creating twice records it twice' is a genuinely useful warning against naive retries, but there is no explicit when-to-use framing against list_transactions/get_transaction, and no prerequisites (e.g., that category keys or ref_id entities must already exist). Guidance is implied 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 cover the safety profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), and the description only reinforces the non-idempotency with 'Adds a record each time' plus an endpoint path. It says nothing about required permissions, which fields the API rejects, or what the response contains beyond a created 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?

Two tight sentences plus an endpoint path, with the WRITE marker and target scope front-loaded. No filler; the endpoint line is borderline but adds precision about resource hierarchy.

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

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

For an 11-parameter mutation with no output schema and sparse schema descriptions, the definition leaves too much unstated: which fields are optional vs required in practice, what withdrawal_date/retreat_date mean for food safety, and what comes back 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?

With 11 parameters and only 27% schema description coverage, the description must carry the load, yet it only clarifies the 'parent' enum (animal/livestock group/field/crop planting) and gives examples for the treatment type. Nine parameters — notably withdrawal_date, retreat_date, cost, amount and technician — go unexplained in 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 ('record a treatment') with concrete examples of treatment kinds and enumerates all four valid target entity types, then gives the exact endpoint shape. An agent can distinguish this from farmbrite_list_treatments or farmbrite_create_note without opening any schema.

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

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

'Adds a record each time' implicitly warns that repeats create duplicates, which is helpful. But there is no explicit routing guidance — nothing says to use farmbrite_list_treatments to verify before writing, or how this differs from adjacent create tools for feedings, harvests or notes.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the response carries current location and custom fields — useful return-content context that annotations don't supply. It does not cover failure behavior (e.g. unknown 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?

Two compact sentences with the result content front-loaded. The raw endpoint path is mildly redundant but gives useful API mapping and costs little.

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?

A one-parameter read tool whose annotations carry the safety profile and whose description states what comes back despite there being no output schema. Only missing piece is error/not-found behavior, which is minor here.

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 animal_id parameter is documented with pattern/length constraints, so the schema does the heavy lifting. The description only restates 'by id'; baseline 3 is appropriate.

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

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

States a specific verb and resource ('One animal by id') and names the returned payload scope (current location, custom fields), which cleanly separates it from farmbrite_list_animals. It never explicitly names the list sibling, so sibling differentiation is implicit rather than stated.

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

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

Usage is implied by 'one animal by id' — fetch when you have an id. There is no explicit when-to-use/when-not or guidance pointing to farmbrite_list_animals for discovering ids, which is the main lookup alternative an agent would need.

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/openWorldHint=true, so the safety profile is covered. The description usefully notes the response includes address data, which annotations don't convey, but adds nothing on permissions, error behavior for unknown ids, or 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?

Two short fragments, zero waste, and the key scoping fact ('one contact by id') comes first. Nothing superfluous 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?

For a single-parameter read-only lookup with full schema coverage and annotations, this covers what an agent needs to invoke it. The missing piece is only the not-found/error behavior, which is minor here.

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 there is a single required contact_id already documented with a pattern. The description adds no format or sourcing detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('contact') scoped to a single record by id, plus the endpoint. The 'one contact by id' phrasing implicitly contrasts with farmbrite_list_contacts, though it doesn't name that sibling to make the differentiation 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: 'one contact by id' suggests fetching a known contact rather than browsing. It never states when to use this versus farmbrite_list_contacts nor mentions any prerequisite.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds only the REST path 'GET /crops/{crop_id}', saying nothing about authentication, not-found behavior, or what the returned planting record contains.

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 terse fragments with zero wasted words and the resource concept front-loaded. The endpoint path partially restates information available elsewhere, but the definition is not 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 single-parameter read tool with full schema coverage, this is close to sufficient, but with no output schema the agent still has no information about the shape of the returned planting record or error cases. 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 coverage is 100% and the single crop_id parameter is documented as 'a Farmbrite id string' with a pattern constraint, so the schema carries the semantics. The description adds nothing beyond 'by id', which is the baseline for full schema 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?

States the specific resource (one crop planting) and the retrieval mode (by id), which cleanly separates it from the sibling list tool farmbrite_list_crops. No explicit sibling naming, but the singular 'one ... by id' 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?

'By id' implies the tool is used when a crop_id is already known, and the sibling farmbrite_list_crops covers discovery. This is only implied; there is no explicit when-to-use or when-not-to-use statement, and no guidance on where an id comes from.

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=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real value by disclosing the return shape — one row per storage location with capacity and remaining quantity — and the underlying endpoint, which annotations do not convey. Pagination behavior is left entirely to the schema.

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

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

Two tight sentences plus an endpoint fragment; the core payload description is front-loaded with zero filler. The trailing 'GET /inventory_types/{inventory_type_id}/inventory' is marginally redundant given the tool name but aids API alignment.

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 the burden of explaining return values, and it does so adequately by enumerating the per-location fields. Combined with full schema coverage of the three parameters and complete annotations, an agent has what it needs to call it correctly.

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

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

Schema description coverage is 100%: inventory_type_id, page, and limit are each documented with format and defaults in the schema. The description adds nothing about parameters beyond implying the type id scopes the lookup, so baseline 3 applies.

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

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

The description names the resource precisely (per-location storage of one inventory item) and enumerates what comes back — warehouse and bin ids/names, capacity, quantity remaining — which makes the tool's purpose concrete. It is distinguishable from farmbrite_get_inventory_type and farmbrite_list_warehouses, though it never states the contrast 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?

It gives a downstream usage pointer ('Use the ids with farmbrite_add_inventory / farmbrite_remove_inventory'), which tells the agent why to call it, but there is no guidance on when to prefer this over farmbrite_list_warehouses or farmbrite_get_inventory_type, and no prerequisites 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=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by disclosing what the response contains (quantity remaining, projected empty date) and the underlying endpoint, though it says nothing about error behavior for a bad 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?

Two terse sentences with the substance front-loaded; nothing is wasted. The endpoint path is mildly redundant but reinforces which resource is queried.

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 one-parameter read with full schema coverage and complete annotations, the description supplies purpose plus the key return fields. No output schema exists, so naming the returned attributes is a meaningful completion rather than 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 coverage is 100% and the single parameter already carries a description with a format pattern and length bounds. The description only restates 'by id' and adds no id syntax, sourcing, or lookup hints 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 and resource ('One inventory item type by id') and names what it returns (quantity remaining, projected empty date). It clearly contrasts with the sibling farmbrite_list_inventory_types by being a single-record fetch, though it never names that 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: 'by id' signals a single-record retrieve versus the list tool. There is no explicit when-to-use, when-not-to-use, or named alternative, so an agent must infer the choice from context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by naming what comes back (member count, filters, member animals) since there is no output schema, but it doesn't clarify what 'filters' means or whether the member animal list is paginated or truncated.

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 payload description; the trailing REST path costs a few tokens but helps API-oriented agents map to the underlying endpoint. No redundancy.

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

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

For a single-parameter read-only getter with full schema coverage and no output schema, the description covers what it returns and what identifies the resource. Only the shape/size of the returned member animals is left unspecified.

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 parameter group_id is fully documented in the schema, including its id-string format and pattern. The description adds only the phrase 'by id', so baseline 3 is appropriate.

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

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

States a specific verb+resource ('One livestock group by id') and discloses the payload shape (member count, filters, member animals), which separates it from farmbrite_list_livestock_groups. It stops short of naming the list sibling explicitly, so the agent must infer that this is the single-record fetch.

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?

'by id' implies the precondition of a known group_id, and the sibling list suggests this is the follow-up detail call. There is no explicit when-to-use statement, no exclusion, and no mention of when the list tool is preferable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the return payload composition (line items, contact, address, totals), which is real context since no output schema exists. It omits any note on permissions or behavior for missing/invalid ids.

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: the returned content is front-loaded, then the REST endpoint. No filler; every clause carries information.

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

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

For a single-param read tool with annotations and no output schema, the description gives enough — what is returned and how it is addressed. A note on error behavior for unknown ids 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?

Only one parameter with 100% schema coverage and an explicit pattern/description in the schema itself. The description only restates 'by id', adding nothing beyond the schema, 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?

Specific verb+resource: retrieves a single order by id, and it enumerates the payload (line items, customer contact, delivery address, totals), which separates it from farmbrite_list_orders. It stops short of naming the sibling it is not, so sibling differentiation is implied rather than stated.

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

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

The phrase 'by id' implies the usage context — fetch a known order rather than search — but there is no explicit when-to-use, when-not, or pointer to farmbrite_list_orders for discovery. Usage must be inferred.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the underlying REST path, but nothing about behavior on an unknown id (empty vs error) or auth requirements — acceptable given the annotation coverage, but not enriching.

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 fragments, front-loaded with the resource and scope, no filler. Slightly clipped to the point of being telegraphic, but nothing is wasted.

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

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

For a single-parameter read tool with full annotations, this is close to sufficient: the agent knows it fetches one plot by id. With no output schema, though, the description gives no hint of what a returned plot contains or how a missing id is signaled, which is the main 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?

Only one parameter and schema description coverage is 100%, with the schema itself explaining that plot_id is a Farmbrite id string with a pattern and length bounds. The description adds no format or sourcing detail beyond what the schema supplies, 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?

Identifies the resource ('field/grow location') and the single-item scope ('by id'), with the endpoint GET /plots/{plot_id} confirming it's a read of one plot. It stops short of naming the obvious sibling farmbrite_list_plots, so the distinction is implied rather than stated.

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

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

'By id' implies this is the single-record fetch versus the list tool, and the presence of farmbrite_list_plots in the sibling set makes the split inferable. However, there is no explicit when-to-use/when-not statement and no guidance on what to do if only a name is known.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes one genuinely useful behavioral detail: the response includes the task's checklist. It omits not-found behavior, error handling, and any auth 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?

Two short sentences, front-loaded with the return payload and followed by the endpoint mapping. Nothing extraneous, though the endpoint mapping is of marginal use to an agent.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so only partially: task plus checklist. For a simple keyed read that is close to adequate, but not-found behavior and response shape detail are absent.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents task_id format and constraints. The description adds nothing beyond 'by id', which matches the baseline for a fully documented single-parameter 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 with scope: 'One task by id with its checklist', which clearly separates it from the list-style sibling farmbrite_list_tasks. It stops short of naming any sibling explicitly, so the differentiation is implied rather than spelled out.

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

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

The phrase 'by id' implies the tool is for fetching a single known task, but there is no explicit statement of when to use this versus farmbrite_list_tasks nor any note about needing a valid id first. Usage is inferable but not guided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the REST endpoint path, hinting this is a direct API passthrough; it says nothing about auth needs, 404/not-found behavior, or what a transaction object contains.

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 terse sentences, zero filler, with the core purpose front-loaded before the endpoint detail. Nothing here could be cut without losing information.

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

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

For a one-parameter read tool with full schema coverage and read-only annotations, the minimum needed to call it correctly is present. However, there is no output schema, and the description does not characterize the returned transaction (fields, money vs. inventory transaction, nesting), leaving the agent blind on results.

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

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

Schema coverage is 100% with a single required transaction_id that already documents the id format and constraints, so baseline is 3. The description's 'by id' adds no syntax, format, or sourcing guidance 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 resource and cardinality ('One transaction by id') and gives the underlying endpoint GET /transactions/{transaction_id}, which makes the single-record retrieval unambiguous. It implicitly contrasts with the list sibling via 'One', but never names farmbrite_list_transactions.

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 id' signals that you need a known identifier, so an agent can infer this is not a search/browse tool. There is no explicit statement of when to use this versus farmbrite_list_transactions or the create/update siblings, and no prerequisites 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (GET /activities) and the shape of returned records, but says nothing about page traversal behavior or that filters are silently ignored on bad input (that detail lives only in the schema).

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

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

A single front-loaded sentence naming the resource and its fields, followed by the HTTP endpoint. Nothing is padded or redundant.

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, listing the returned fields is valuable and largely compensates. Pagination and filtering semantics are fully covered by the schema, leaving only sibling disambiguation as an unmet need.

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 page/limit/filters/sort_by/sort_dir all documented in the schema including operator syntax and silent-ignore behavior. The description adds no parameter guidance beyond what the schema already states, 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?

Specific verb 'List' plus resource 'calendar/schedule activities', with the fields returned enumerated in parentheses. It does not, however, distinguish this from the closely related sibling farmbrite_list_tasks, which an agent could easily confuse with schedule activities.

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 indication of when to use this versus list_tasks or the create_* schedule tools; there are no exclusions or alternative routing. The reader has to infer that this is the read path for the same resource family.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds 'newest data included', giving a hint about ordering/recency, and exposes the GET route; it does not discuss pagination behavior or response shape, but with annotations carrying the safety profile this is adequate rather than 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?

One front-loaded sentence naming the record types, followed by the endpoint path. Every element is compact; the endpoint string is mildly redundant with the name but costs little.

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

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

For a paginated list tool with 5 params and no output schema, the description covers what is being listed but says nothing about ordering guarantees beyond 'newest', empty results, or how paging interacts with sorting. The schema fills most of the parameter gap, leaving the description merely sufficient.

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 page, limit, sort_by, sort_dir and animal_id are all documented in the schema itself. The description adds nothing beyond implying that animal_id identifies 'one animal' — baseline 3 is correct when the schema does the heavy lifting.

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

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

The description names the concrete resource (weight, height, temperature, condition score, fecal-count records) and scopes it to a single animal, which lets an agent separate it from farmbrite_add_animal_measurement and farmbrite_get_animal. The verb is left implicit — only the title says 'List' — so it is clear but not maximally sharp.

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 retrieval of an animal's measurement history, but never states when to choose it over siblings such as farmbrite_get_animal or farmbrite_add_animal_measurement, nor any prerequisites (e.g., a valid animal id must already exist). Usage is inferred rather than instructed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the default result-filtering behavior (active-status only) and the underlying endpoint, which an agent could otherwise get wrong. Return shape and pagination are left to the schema.

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

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

Two dense sentences with no filler: field list first, then the important default-filtering caveat, then the endpoint. Nothing is wasted and the key constraint 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?

With 9 params, nested filters, no output schema, and only a single sentinel status enum documented, the field enumeration in the description usefully substitutes for a return schema. It stops short of explaining pagination or the total/next_page shape an agent needs to iterate pages.

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 description's only parameter-relevant statement — that status filtering is needed to see Sold/Deceased/etc. — is already documented verbatim in the status parameter description. Baseline 3 applies when the schema does all the work.

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 ("livestock records") and enumerates the returned fields, so an agent knows exactly what this returns versus farmbrite_get_animal. It never explicitly routes the agent to a sibling (e.g. get_animal for a single record), which keeps it just 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 critical usage rule is spelled out: Farmbrite returns only active-status animals unless you pass a status filter, with the full set of non-active statuses named. That's genuinely actionable context. It lacks explicit when-not guidance or named alternatives for other listing needs.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the returned field names (name, company, email, phone, type, label) which is useful, but says nothing about pagination behavior, result limits, or that filters silently ignore bad input (that is only in the schema).

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

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

Two compact clauses with no wasted words; the purpose and returned fields are front-loaded. It is perhaps over-terse, but nothing is filler.

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

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

The rich parameter schema and annotations carry most of the load, and the description adds the return field list. However, with no output schema, it omits pagination/next_page behavior and filtering guidance that an agent calling this list tool would benefit from.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lists entity fields but does not explain the parameters themselves beyond what the schema already documents in detail (filters, sort_by, page, limit).

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 (contacts) and clarifies the resource's scope with examples (customers, suppliers, vendors). The field list and GET /contacts endpoint pin down what it returns, making it easy to distinguish from write siblings, though it never names farmbrite_get_contact as the single-record alternative.

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

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

There is no guidance on when to use this versus farmbrite_get_contact or farmbrite_create_contact, and no notes on pagination workflow or when to prefer the filters parameter. Usage is only inferable from the verb 'List' and the endpoint hint.

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, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds the returned field list and the endpoint ('GET /crops'), which is useful context, but does not disclose pagination behavior, rate limits, or filtering semantics beyond what the schema provides.

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 that efficiently conveys the core purpose and returned fields. The trailing 'GET /crops' is a minor implementation detail but does not detract significantly from clarity.

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 full schema description coverage and annotations covering safety, the description is largely complete: it identifies the resource, lists returned fields, and is sufficient for an agent to recognize the tool. It could mention filtering/pagination at a high level, but the schema already covers those 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 description coverage is 100%, so the schema fully documents all seven parameters, including the nested filters object. The description adds no parameter-level meaning beyond listing returned fields, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('crop plantings') and enumerates the fields returned, making the tool's function clear. However, it does not differentiate from related siblings like farmbrite_list_plants or farmbrite_list_plots, leaving ambiguity about when this tool is preferred over those.

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

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

The description offers no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It merely states what the tool does, leaving the agent to infer usage from the name and schema.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (amount, cost, date, feed type, inventory used), which is useful, but says nothing about pagination behavior, ordering, or empty-result semantics beyond what the schema's page/limit descriptions 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?

Two short sentences, front-loaded with what the record contains and followed by the exact endpoint shape. Nothing is wasted and the reader gets the core fact in the first few words.

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

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

With no output schema, the description compensates by enumerating the returned fields, which is exactly what an agent needs to decide whether to call this. Pagination and id constraints are fully covered by the schema; only ordering and result-shape details are missing, which is minor.

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 four parameters (including the animals/livestock_groups enum and the pagination fields) are already documented in the schema. The description only echoes 'one animal or livestock group', adding no syntax, id format, or pagination guidance beyond the schema, 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 resource (feeding records), its scope (one animal or livestock group), and even the REST endpoint, so the agent can immediately tell what is returned. It does not explicitly contrast with the write sibling farmbrite_create_feeding, but the read intent is unambiguous from 'records' plus the GET path.

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: the parent/parent_id requirement makes clear it lists feedings for a single animal or group, and the endpoint notation reinforces that. There is no explicit 'use this when…' guidance, no exclusions, and no pointer to the sibling that creates feedings versus this one that lists them.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned-field inventory ('GET /grazings' is just the endpoint restated) but says nothing about result volume, pagination behavior, or whether a field with no grazing record is omitted or empty.

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, with the payload contents front-loaded ahead of the endpoint reference. 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?

With five optional params, all documented in schema, and no output schema, the description usefully enumerates the expected return fields, which partially substitutes for the missing output schema. It falls short only on paging/result-size expectations and on how grazing status relates to the plots/livestock-group tools.

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 page/limit/filters/sort_by/sort_dir are fully documented in the schema, including the filter operator syntax and the silent-ignore caveat. The description adds no parameter meaning of its own, which is acceptable at this coverage level but not additive.

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 (grazing summary), and itemizes the fields returned (animals present, days rested, rest days required, last grazed), including a clear per-field/per-pasture scope. It does not explicitly distinguish itself from list_plots or list_livestock_groups, which are the nearest 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?

No when-to-use statement, no prerequisites, and no mention of alternatives such as listing plots or livestock groups if the agent instead wants the underlying entities rather than grazing status. Usage is only inferable from the resource 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=true and destructiveHint=false, so safety is covered. The description earns credit by disclosing the shape of what comes back (quantity, unit, grade, price, date, inventory added) and the underlying GET path, which is valuable since no output schema exists.

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

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

Two compact sentences: the resource and returned fields first, then the endpoint form. No filler, correctly 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 read-only list tool with no output schema, listing the returned fields plus the endpoint covers the essentials; pagination guidance lives entirely in the schema descriptions, so nothing critical is missing.

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

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

Schema coverage is 100%, so page, limit, parent and parent_id are fully documented in the schema. The description only echoes the parent enum ('animal or crop planting') and the endpoint template, 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+resource+scope: harvest records belonging to one animal or crop planting, and names the returned fields. This clearly separates it from farmbrite_create_harvest and from farmbrite_list_crops/farmbrite_list_animals, though it does not name 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?

Usage is only implied — you call it to inspect harvests of a given parent. There is no explicit statement of when to prefer it over another tool, no prerequisite or auth context, and no mention of how to page through results (the schema carries that 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?

Annotations already establish this as a non-destructive read-only operation, and the description adds useful context by naming the returned business fields such as quantity remaining, unit, value, and low-stock alert level. It does not describe pagination behavior, but the schema covers that parameter-level behavior.

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

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

The description is two tight sentences, front-loads what the tool returns, and wastes no space. The endpoint reference is brief and does not distract from the purpose.

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

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

There is no output schema, so the description usefully names the key fields returned and gives examples of inventory item types. Combined with the fully documented parameters, this is enough for correct selection and invocation, though slightly more context about pagination or filtering behavior could help.

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 page, limit, filters, sort_by, and sort_dir are already documented in structured data. The description adds no additional parameter detail, which is acceptable at the baseline for high schema 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?

The description gives a specific verb and resource: listing inventory item types, with examples of the types returned. It clearly separates this list operation from the singular get_inventory_type by name and verb, though it does not explicitly point to that sibling as the alternative.

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

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

The list verb implies that this tool is for browsing inventory item types, but there is no explicit when-to-use guidance versus farmbrite_get_inventory_type or other inventory-related siblings. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only the endpoint path and the returned field set; it says nothing about pagination behavior or that unknown filters are silently ignored (that lives in the schema).

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

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

A single terse sentence with the resource and output fields front-loaded; every token earns its place. It is arguably too thin rather than verbose, which affects other dimensions rather than this 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 read-only list endpoint with full schema documentation and clear annotations, the description covers what the tool is and what it returns. Minor gaps: no mention of pagination or that filters are supported, but these are documented in 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%, including detailed filter operator syntax and sort semantics, so the schema carries the parameter burden and baseline 3 applies. The description contributes nothing beyond naming returned fields, not the inputs.

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 livestock groups') and names the returned fields (id, name, type), which lets an agent distinguish it from farmbrite_get_livestock_group. It does not explicitly contrast with the singular fetch tool, 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?

No guidance on when to use this list tool instead of farmbrite_get_livestock_group, and no mention of the pagination or filter strategy despite those being the main usage decisions. The agent must infer usage 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this is a GET over a parent-scoped subresource and lists which fields come back, but says nothing about paging through results or result 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?

Two tight sentences: what a note contains and where notes hang. Scope is front-loaded and nothing is redundant.

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 enumerates the returned fields (description, category, date, keywords), which is the main thing an agent needs. The remaining gap is paging behavior, which is at least documented in the schema's page/limit descriptions.

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 real value by mapping the enum tokens to domain concepts ('plots' = field, 'plants' = plant type, 'crops' = crop planting, 'inventory_types' = inventory type), which an agent would otherwise have to guess. Page and limit semantics remain schema-only.

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 the resource (notes) and its attachment scope (animal, field, plant type, crop planting, inventory type), plus the underlying GET endpoint, so the agent can tell it apart from farmbrite_create_note. It stops short of explicitly contrasting with the write sibling, but the retrieval intent is unmistakable.

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

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

Usage is implied: call it when you need the notes on a known parent record. There is no explicit when-to-use statement, no mention of the create_note alternative, and no note about pagination or repeated calls being needed to gather all notes.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the raw endpoint "GET /orders" and a field list, with no information about pagination behavior, default result size, or that unknown filter fields are silently ignored (a trap documented only in the schema).

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

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

Two compact fragments, front-loaded with the verb and resource, with zero filler. Slightly under-weight for the tool's complexity but nothing is wasted.

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, listing the returned fields (status, payment status, total, dates, contact, delivery type, invoice number) is genuinely useful for shaping follow-up calls. However, for an 8-parameter list tool with a nested filters object, the description says nothing about pagination, sorting defaults, or filter behavior, leaving the schema to carry those burdens.

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 filters, sort_by/sort_dir, status, payment_status and contact_id all documented including operator syntax and the silent-ignore caveat. The description adds no parameter meaning beyond listing some of the same fields, so the schema does all the work and 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 ("List sales orders") and enumerates the record fields returned, which lets an agent infer it differs from farmbrite_get_order (single order) and farmbrite_create_order/update_order. It stops short of naming those siblings explicitly, so the differentiation is inferential rather than stated.

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

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

No when-to-use or when-not guidance, no mention of the single-order sibling farmbrite_get_order, and no note about paging through results before narrowing with filters. The agent must infer usage entirely from 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds only the endpoint path and the field names visible in responses; it does not discuss pagination flow, result volume, or the silent-ignore filter behavior beyond what the schema states.

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 plus endpoint reference, with no filler. It is arguably too terse rather than bloated, but nothing wastes space.

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 full schema coverage and annotations, the definition is usable but thin: it omits sibling disambiguation (plants vs crops) and any indication of what a page of results contains beyond four sample 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 page, limit, filters, sort_by and sort_dir are already fully documented in the schema, including the operator syntax and silent-ignore caveat. 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 and resource ('List plant types/varieties') and even previews the fields returned, plus the underlying endpoint GET /plants. However, it never distinguishes itself from close siblings like farmbrite_list_crops, leaving the agent to infer which list to call.

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 farmbrite_list_crops or the get_* lookups, and no stated prerequisites. The agent gets an implied read-only listing but must infer the selection criteria 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and returned field inventory, but says nothing about pagination behavior, result ordering defaults, or how the silent-ignore filter behavior affects results.

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 terse fragments, front-loaded with the resource and its returned fields, then the endpoint. Zero wasted words and nothing 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, enumerating returned fields (title, type, size, status, grazing rest days) usefully compensates, and the schema fully carries the five optional parameters. Only minor gaps remain, such as what the paged envelope looks like and whether all listed fields are always present.

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

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

Schema description coverage is 100%, so the schema already fully documents page, limit, filters, sort_by, and sort_dir, including the Farmbrite silent-ignore caveat. 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?

States a specific verb (List) and resource (fields/grow locations), enumerates the returned fields, and gives the backing endpoint GET /plots. It is clearly distinguishable from farmbrite_get_plot, but never explicitly contrasts with it or with farmbrite_list_grazing_summary, 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?

Only the implied 'list' semantics indicate when to use it. There is no guidance on when to prefer this over farmbrite_get_plot for a single plot or over farmbrite_list_grazing_summary for grazing data, 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the shape of a task record, which is useful context, but says nothing about pagination volume, ordering defaults, or how the 'complete' flag interacts with filters.

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 compact sentence plus endpoint, front-loaded with the payload of interest; nothing is padded or redundant.

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 parenthesized field list does the work of describing return values, and all seven parameters are fully documented in the schema. What's missing is behavioral detail on paging and filter semantics, which the description leaves entirely to 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 the baseline is 3. The field list (title, status, priority, assignee, due/end time, etc.) loosely suggests what can be used in 'filters' and 'sort_by', but it uses human labels rather than the API field names the schema asks for, so it adds only marginal meaning.

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

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

The description names a specific verb+resource (list tasks) and enumerates the fields each task carries, plus the backing endpoint GET /tasks. It clearly differs from farmbrite_get_task and farmbrite_create_task by enumeration semantics, though it never explicitly contrasts with 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?

There is no statement of when to use this listing versus farmbrite_get_task (single record) or how paging should be driven; the only hints are schema parameters. Guidance is absent, not merely 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (GET /transactions) and the returned field set, but says nothing about paging behavior or result ordering beyond what the schema already documents.

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 line that leads with the operation and resource, then lists the fields, then the endpoint. No filler and nothing 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, enumerating the returned fields (type, amount, date, vendor, category, links, description) is genuinely useful and covers the return shape. Pagination and filtering details live in the schema, so nothing critical is missing, though the absence of any note about paging through results is 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 description coverage is 100%, including a detailed explanation of the nested filters object and its silent-ignore behavior, so the schema carries the parameter burden. The description adds no parameter-level meaning (e.g. which field names are valid in filters, useful sort_by values), so baseline 3 applies.

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

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

Names a specific verb (List) and resource (income/expense transactions), and enumerates the fields returned so the agent knows the payload shape. It is distinguishable from farmbrite_get_transaction and farmbrite_create_transaction by the plural 'List', though neither 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?

There is no guidance on when to use this versus farmbrite_get_transaction (single record) or farmbrite_list_activities, and no stated preconditions. Usage is only inferable from the tool name and the word '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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description contributes the returned field list (type, product, amount, cost, date, withdrawal date, technician), which is genuinely useful given there is no output schema, but it says nothing about pagination, ordering, or empty-result behavior.

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

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

Two sentences, no filler, with the resource and returned fields front-loaded and the endpoint template appended as a compact scoping cue. 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 full schema coverage and no output schema, the description does the important extra work of enumerating returned fields. The only shortfall is the absence of any note on pagination flow or result ordering, both of which an agent must piece together 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 four parameters are already documented, including the parent enum and the next_page pagination convention. The description's 'one animal, field or crop planting' phrasing only loosely maps the enum values and adds no syntax or format detail beyond the schema. 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 the resource (treatment records), enumerates the returned fields, and scopes it to a single animal, field, or crop planting. The listing verb is only implied by the tool name, but the REST endpoint template makes the operation unambiguous. It is clearly a distinct resource from siblings like farmbrite_list_activities or farmbrite_get_animal, though it never names them.

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 routing to related siblings such as farmbrite_create_treatment (to add a record) or farmbrite_get_animal (for the parent entity itself). The agent must infer from the endpoint template that exactly one parent type plus id is 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, destructiveHint=false and openWorldHint=true, so the description only needs to add context. It adds the underlying endpoint (GET /warehouses) and the returned fields, which is modest added value, but says nothing about pagination limits, ordering defaults, or rate/consistency behavior.

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

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

Two short sentences plus a bare endpoint reference, with the resource and its returned fields front-loaded and zero filler. Every clause carries information.

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

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

No output schema exists, so naming the returned fields is genuinely useful, and the read-only safety profile is covered by annotations while all five params are fully described in the schema. Slightly short of complete because the relationship to the near-duplicate farmbrite_get_inventory_locations is left unexplained.

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 page/limit/filters/sort are already fully documented in the schema, and the description does not elaborate on any of them. The listed fields (name, description, internal id) are return values, not parameters, so they do not add parameter semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List storage locations (warehouses) for inventory') and even previews the returned fields, so the agent knows exactly what comes back. It does not explicitly differentiate from the confusingly similar sibling farmbrite_get_inventory_locations, which keeps it from 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 line 'Use the ids when adding or removing inventory' explains the downstream purpose of the result, which implies a workflow context. But there is no statement of when to prefer this over farmbrite_get_inventory_locations or any exclusion/alternative 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 mark the tool as destructive and non-idempotent, and the description reinforces this by stating that repeating removes stock again and that the action cannot be undone except by adding stock back. It stops short of describing permissions or rate limits, but adds meaningful consequence detail beyond the structured hints.

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

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

The description is tightly front-loaded with the write operation and key caveats, then ends with the endpoint. Every sentence adds useful information without repetition or 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 destructive inventory mutation, the description covers the essential behavioral risks: non-idempotence, irreversible stock reduction, and the only in-server recovery path. It does not address the optional parameters or permissions, but the annotations and schema cover enough that the definition is largely complete.

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

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

The schema already describes the three required IDs and the adjustment quantity, but three optional parameters (date, lot_number, description) lack schema descriptions. The tool description does not compensate by explaining those fields or adding meaning beyond the existing parameter documentation.

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

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

The description states a specific verb and resource: taking stock out of an inventory item in a storage location. It explicitly labels the operation as a WRITE and names the endpoint, making it clearly distinguishable from add/read inventory 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?

It gives concrete usage contexts (use, loss, sale) and explains the consequence of repeating the call. It does not explicitly name the alternative tool for adding stock back, but the implication is clear enough for an agent to infer the inverse operation.

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 flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description correctly reinforces this with 'Overwrites previous values' plus the crucial partial-update semantics ('only the fields you pass are sent'). It adds real behavioral value beyond the annotations, though it says nothing about permissions, error behavior, or whether a status change triggers side effects (e.g. removing from a livestock group).

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

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

Three tight sentences: the WRITE prefix and scope land first, the conditional requirement second, the overwrite warning third, with the endpoint as a compact appendix. 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 19-parameter destructive mutation with strong annotations and no output schema, the description covers the essentials an agent needs: partial vs full update, the overwrite risk, and the status/death_date dependency. It leaves a minor gap on what is returned and on whether unlisted-but-required-field combinations can fail.

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 21% across 19 parameters, so the description must compensate and it only partly does: it clarifies partial-update behavior, enumerates several status values, and ties death_date to specific statuses. The remaining parameters (sale_date, birth_date, weight, tag_number, father_id/mother_id, market_price, deceased_reason) get no semantic help, though most are self-describing by name.

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 ('change an animal's fields') plus the underlying endpoint (PUT /animals/{animal_id}), which makes it unambiguously the mutation counterpart to farmbrite_create_animal and farmbrite_get_animal. It does not name a 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?

Gives the key operational rule that statuses Butchered, Culled and Deceased require death_date, which is genuine when-to-use guidance an agent could not infer. It never names an alternative tool or a when-not-to-use case, so it is clear context rather than full routing guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds real context: it is a partial update since only supplied fields are sent, and it overwrites prior values for those fields. It does not state what happens to omitted fields (left untouched vs cleared) or any auth/permission needs, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the 'WRITE:' signal and the endpoint, with zero filler. Every clause carries information an agent needs.

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?

Annotations cover the safety profile and there is no output schema to explain, but for an 8-parameter destructive open-world mutation the description says nothing about the response, error behavior, or which contact_id form is valid beyond the schema. Adequate for the happy path only.

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 13%, so the description must compensate, and it partially does by explaining the patch-style semantics of the supplied fields. However it names none of the seven updatable fields (cell, email, phone, company, first_name, last_name, description), leaving field-level meaning entirely to property names.

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 (change fields of an existing contact), leads with a 'WRITE:' marker, and gives the endpoint PUT /contacts/{contact_id}. That cleanly separates it from farmbrite_create_contact and the read-only get/list 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 parenthetical 'only the fields you pass are sent' implies partial-update usage, so the agent can infer when this is appropriate versus a full create. But it never explicitly says when to use this over create_contact, nor any prerequisites such as needing an existing contact_id from a list/get call.

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 a destructive, idempotent, open-world write, so the safety profile is covered. The description adds genuinely new behavioral context: Farmbrite may trigger customer notifications on some status changes depending on account settings — a real side effect an agent should weigh. It stops short of covering failure modes or whether arbitrary status transitions are permitted.

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 with zero filler, front-loaded with the 'WRITE:' marker so the mutation nature is the first thing read. The endpoint reference is a compact way to convey path parameter usage.

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 three-parameter status-mutation tool with no output schema, this covers purpose, mutable surface, and the notable notification side effect. Missing are return-value expectations and any statement about invalid transitions or whether the order must already 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 coverage is only 33% (only order_id is documented in-schema), so the description must compensate; it does by naming the two mutable fields, noting they are independently optional ('and/or'), and giving example values ('Paid', 'Delivered') that anchor the enums. It does not explain the semantics of individual status values or allowed transition order, leaving a modest 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 and resource (change an order's status and/or payment status) plus the HTTP method and path, which makes it immediately distinguishable from farmbrite_create_order, farmbrite_get_order and farmbrite_list_orders. The scope limit — only status and payment status are changeable — prevents the agent from expecting a general order-field editor.

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?

Clear about the context of use (marking orders Paid/Delivered or moving through the status list) and implicitly excludes other order edits by naming only two fields. It does not name an alternative tool or state prerequisites, so it falls short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description earns credit for explaining why ('Overwrites previous values', 'only the fields you pass are sent'), which reconciles the destructive hint with partial-update semantics. It omits auth/permission needs and error behavior for invalid status values.

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 WRITE marker and endpoint, with no filler. Every clause carries operative information (mutation type, partial semantics, overwrite, shortcut flag).

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 mutation with no output schema, the description covers the essentials: partial update, overwrite risk, and the completion convention. It leaves unclear how to clear/unassign a field, status value validation, and failure behavior.

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

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

Schema coverage is 78%, so the baseline is 3, but the description adds a cross-parameter rule the schema cannot express: only supplied fields are sent. The 'set complete=true to mark it done' sentence largely repeats the schema's own description of that 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?

States a specific verb ('change a task') plus the resource, and immediately clarifies the partial-update scope and the complete=true shortcut. It is unambiguous against the sibling farmbrite_create_task and farmbrite_get_task without opening either schema.

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

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

Makes clear this is for modifying an existing task and that only passed fields are sent, which tells the agent when this is preferable to a create call. It stops short of naming an explicit alternative or when-not condition.

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