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

With no annotations, the description carries the full behavioral burden, and it does add one genuinely non-obvious trait: the invoice is not finalized and gets no number, so finalization is manual. Beyond that it is silent on permissions, whether the returned draft ID can be chained into create_line_item, and any side effects or limits — significant gaps for a mutation with 12 parameters.

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

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

Two short sentences, zero filler, and the most decision-relevant fact — that the result is an unfinalized draft — is front-loaded immediately after the core action.

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

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

For a 12-parameter mutation with no annotations and no output schema, the description covers the critical draft/finalization behavior but leaves open what the tool returns (e.g., the new invoice ID) and how it pairs with line-item creation. It is adequate but leaves real gaps for a tool of this complexity.

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

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

Schema description coverage is 100%, so every parameter (company_id, document_type_id, invoiced_on, invoice_type_id defaults, etc.) is already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Creates a new draft invoice') and scopes it precisely as a draft, which separates it from the nearby create_invoice_from_previous and create_invoice_like_last_for_client siblings. It stops short of explicitly naming those alternatives, so it's clear but not fully differentiated.

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

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

It establishes the important precondition that this produces a draft requiring manual finalization, which tells the agent when the output is usable. However, it never states when to prefer this over the two sibling creation tools or what prerequisite data (line items, company) is needed, leaving usage largely implied.

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

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

No annotations are supplied, so the description carries the full behavioral burden, and it does disclose one useful constraint: the invoice must be a draft. Beyond that it is silent on permissions, whether re-linking an already-attributed invoice is idempotent or an error, and what the response contains. For a mutation tool with zero annotation coverage this leaves meaningful gaps.

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 core action, with nothing bloated. The second sentence is partially redundant with the first, repeating that the invoice is connected to a budget, which keeps it just short of a 5.

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 operation is fairly self-contained and the schema is fully annotated, but with no annotations and no output schema the definition should still cover side effects, failure modes, and the read counterpart. It covers the core action and the draft-state constraint but stops there.

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

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

Schema description coverage is 100%, so all five parameters are already documented and the baseline is 3. The description adds only marginal gloss ('budget/deal' for deal_id, 'allocated amount' for amount) and no format, range, or period semantics for date_from/date_to.

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 ('Link') with both resources ('draft invoice', 'budget/deal') and the allocated amount, so the agent knows exactly what is being created. It does not, however, name or distinguish itself from its obvious sibling 'productive_list_invoice_attributions', so sibling differentiation is left to the reader.

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 second sentence only restates the purpose ('connects the invoice to a budget for financial tracking') rather than telling the agent when to reach for this tool. There is no mention of prerequisites, no exclusions, and no pointer to 'productive_list_invoice_attributions' or 'productive_create_invoice' as alternatives.

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

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

With no annotations, the description carries the full behavioral burden and does meaningful work: it discloses the resulting state ('saved as a draft — not finalized or assigned a number') and what gets copied (line items and budget links). It stops short of mentioning permissions, error conditions, or what the response returns.

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, front-loaded with the core action and state outcome, then the workflow hint. Every clause earns its place with no redundancy.

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

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

For a mutation tool with no annotations and no output schema, the description adequately covers purpose, resulting state, copied fields, and a workflow prerequisite. The notable remaining gap is that it does not state what the call returns (presumably the new invoice ID) nor clarify the optional override parameters.

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

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

Schema description coverage is 100%, so the schema already documents all five params including the required source_invoice_id and the four override fields. The description adds no parameter-level detail (e.g., that note/pay_on/subject/invoiced_on are optional overrides), leaving it at the baseline.

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

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

States a specific verb and resource ('Creates a new draft invoice') and specifies the source mechanic ('based on a previous invoice, copying line items and budget links'). It is distinct from the plain create_invoice sibling by scope, though it never explicitly contrasts itself with the very similar productive_create_invoice_like_last_for_client.

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

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

Provides one workflow prerequisite ('Use productive_get_invoice first to inspect the source invoice'), which implies context of use. However, it gives no when-to-use vs. the alternative clone/create-invoice siblings, and no exclusions.

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

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

With no annotations, the description carries the burden and does well: it discloses that line items and budget links are copied and that the result is a draft that is neither finalized nor numbered. It does not mention permission requirements or what happens on conflicting overrides, keeping it just short of full 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?

Two tightly written sentences that front-load the core action and then the important draft-state caveat. No wasted words.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential behavioral facts (draft state, copied content, default numbering behavior). Missing only secondary details like auth scope or override-conflict 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 description coverage is 100%, so all six parameters are already documented in the schema. The description only restates the 'Nth most recent' semantics of how_many_back, adding no format or default detail beyond what the schema provides. 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 (creates) and resource (draft invoice) with the defining mechanism: cloning a client's most recent invoice. This clearly differentiates it from create_invoice and create_invoice_from_previous in the sibling list.

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 '(or Nth most recent)' implies when to reach for this tool, but it never names alternatives like productive_create_invoice or productive_create_invoice_from_previous, nor states when cloning is preferable to creating from scratch. Usage is implied rather than 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?

With no annotations present, the description carries the full behavioral burden. It does disclose one genuinely useful behavioral constraint — the target invoice must be a draft — but omits permissions/auth requirements, whether the operation recalculates invoice totals, and any rate-limit or failure 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 tightly written sentences with zero filler; the core action and the draft-invoice constraint are front-loaded before the explanatory detail.

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

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

For a mutation tool with 9 parameters, no annotations, and no output schema, the description covers the essentials of what the tool does and the draft precondition. It leaves gaps on optional-parameter usage (discount, position, service_type_id) and provides no context on outcomes, which the absence of an output schema makes slightly more noticeable.

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 schema already documents all nine parameters including unit_id enum values and required flags. The description restates that description/quantity/unit_price define the billable row and that tax_rate_id sets per-line tax, which is mildly reinforcing but adds no syntax or format detail beyond the schema.

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

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

States a specific verb+resource (create a line item) and adds the scope constraint 'on a draft invoice,' which meaningfully narrows what the tool does. It does not explicitly name siblings like update_line_item or list_line_items, so 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?

The phrase 'on a draft invoice' implies a precondition and context of use, which is more than nothing. However, it never says when to use this versus update_line_item, list_line_items, or delete_line_item, and gives no guidance on error/failure cases like a non-draft invoice.

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?

No annotations are provided, so the description carries the full behavioral burden. It does not disclose authentication/permission requirements, what the created project returns, defaults applied to omitted fields like workflow_id, or any side effects. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

Three short sentences, front-loaded with the core action, followed by required inputs and the helper-tool pointer. 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?

Covers the essentials for calling the tool, but omits workflow_id entirely and gives no indication of the return payload or error behavior. With no output schema and no annotations, the description leaves real gaps even if the schema covers parameter names.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, and the description largely restates the required ones. It adds the dependency hint that company IDs come from productive_list_companies, but does not clarify workflow_id or the meaning of project_type_id 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 ("Create a new project in Productive.io") and is clearly distinguishable from the sibling read/update tools (productive_get_project, productive_update_project, productive_list_projects). An agent can identify the operation immediately.

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

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

Specifies the required inputs (name, project_type_id) and the optional company association, and explicitly routes the agent to productive_list_companies for company ID lookup. It gives clear usage context but no when-not-to-use guidance or alternative creation paths.

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

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

With no annotations, the description carries the full behavioral burden, yet it says nothing about required permissions, side effects on the parent list/project, whether the call is idempotent, or what the response contains. The only added context is the structural note that task_list_id belongs to a project.

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

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

Two sentences, front-loaded with the action and required inputs, followed immediately by the discovery path. 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 seven-parameter mutation tool with no annotations and no output schema, the description covers required inputs and ID discovery but omits creation semantics and return behavior, which an agent must otherwise guess.

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

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

Schema coverage is 100%, so the schema already documents all seven parameters and even repeats the ID-discovery hints. The description adds one piece of meaning beyond it: that task_list_id belongs to a project, clarifying the hierarchy an agent must respect.

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 new task in Productive.io') and the required inputs, which distinguishes it clearly from siblings like productive_get_task, productive_update_task, and productive_list_tasks.

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

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

Gives an explicit prerequisite (title and task_list_id) and routes the agent to productive_list_tasks with a project_id to discover valid task_list IDs. It doesn't contrast against productive_update_task or explain when creating is inappropriate, so it stops short of the top band.

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

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

With no annotations, the description carries the full behavioral burden and discloses almost none of it: it does not say the deletion is irreversible, whether it requires specific permissions, what happens if the line item belongs to a non-draft invoice, or what the response looks like. The draft-invoice scope is the only behavioral constraint offered.

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

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

A single front-loaded sentence with no filler; the scope constraint appears immediately after the action. It is efficient, though arguably too terse for a destructive operation with no annotations.

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

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

For a destructive mutation with no annotations and no output schema, the description should at minimum signal irreversibility and permission requirements. The draft-invoice constraint helps, but the safety and error semantics an agent needs before calling this 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?

Schema description coverage is 100% for the single id parameter, so the schema already fully documents it. The description adds no syntax, format, or ID-source detail beyond what the schema provides, 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 (Delete) and resource (line item) and adds a scoping qualifier (from a draft invoice), which separates it from productive_create_line_item and productive_update_line_item. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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

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

'From a draft invoice' implies the precondition that only draft-invoice line items are deletable, which is useful routing context. However, it never says when to delete versus update, and gives no guidance for non-draft invoices or what to do 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?

No annotations are provided, so the description carries the full burden. It implies a read but says nothing about permissions, error behavior when the ID is unknown, pagination, or what 'full details' actually comprises.

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

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

A single tight sentence with the key constraint ('by ID') front-loaded. No padding, though the 'with full details' clause is vague filler.

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

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

For a simple two-parameter read tool with full schema coverage, the description is minimally adequate. Without annotations or an output schema, 'full details' should have been made concrete (e.g. what fields or related resources are returned).

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

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

Schema description coverage is 100%, so both parameters are already documented. The description adds no meaning beyond the schema, e.g. no guidance on the comma-separated include format or valid related resource names. Baseline 3 applies.

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

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

States a specific verb (get), resource (company), and scope (single, by ID) on Productive.io. This clearly separates it from productive_list_companies, though it does not explicitly say so.

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

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

No when-to-use guidance, no mention of alternatives such as productive_list_companies, and no prerequisites or exclusions. The agent must infer that this is the detail-fetch counterpart to the list tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read-only operation and 'full financial details' hints at return content, but there is no mention of auth/permission requirements, error behavior for missing or inaccessible deals, or response shape. For a tool with zero annotation coverage, this is thin.

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

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

A single front-loaded sentence with no wasted words; the resource and scoping constraint come 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?

There is no output schema and no annotations, so the description is the only place to convey return behavior; it gestures at this with 'full financial details' but does not enumerate what is returned. Adequate for a simple two-parameter getter, but not fully 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 description coverage is 100%, so both the id and include parameters are already documented in the schema (including the example include values). The description adds nothing beyond the schema, which is the expected baseline 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?

States a specific verb (Get) and resource (deal/budget) and scopes it to a single record by ID, which distinguishes it from productive_list_deals. It does not, however, explicitly name sibling getters or note that it is the single-record counterpart to the list 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 says what it fetches but gives no guidance on when to use it versus productive_list_deals or other read tools, and no prerequisites are mentioned. Usage is only implied by 'single...by ID'.

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?

No annotations are supplied, so the description carries the burden; 'Get' clearly signals a non-mutating read and it says what data is returned, but it never addresses permissions, behavior on a missing/invalid ID, or any rate/limits 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 tight sentences, front-loaded with the core lookup action and with the use-case hint appended. No filler or repetition of the tool name.

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 no output schema, the description usefully previews the returned fields, which the schema cannot convey. The main gap is absent guidance on error/nonexistent-ID 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 100% with a single documented 'id' parameter, so the baseline is 3. The description only restates that lookup is by ID and adds no format, prefix, or validation detail beyond the schema.

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

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

States a specific verb+resource ('Get full invoice details by ID') and enumerates the notable content (line items, attributions, company, document type, subsidiary), which cleanly distinguishes it from the sibling list_invoices and the create/update invoice tools.

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

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

Gives an explicit when-to-use ('Use this to inspect an invoice before cloning it'), which points the agent at the clone/create-from-previous flow. It doesn't name alternatives such as list_invoices or spell out when *not* to use it, so it falls short of a full 5.

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

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

With no annotations, the description carries the full behavioral burden, and it delivers little. 'Get details' implies a read, but nothing is said about whether this requires authentication, what happens on an unknown ID, or what data is returned.

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

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

A single sentence with zero padding and the key qualifier ('by ID') up front. It is efficient, though arguably under-specified rather than truly concise.

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

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

For a simple two-parameter read tool with no output schema, the description covers the core operation adequately. However, the absence of any mention of the include expansion parameter or of behavioral expectations leaves minor but real gaps.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema and this is the baseline. The description's 'by ID' restates the required id parameter without adding format or validation detail, and it ignores the optional include parameter entirely.

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 ('details for a specific person by ID'), which is unambiguous. It does not explicitly distinguish itself from the sibling productive_list_people, though 'by ID' implies a single-record fetch rather than a collection listing.

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

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

No when-to-use guidance is given. The description never names productive_list_people as the alternative for browsing people, nor does it state the precondition that a known person ID is required to use this tool.

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

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

No annotations are supplied, so the description carries the burden, and 'Get' implies a read-only retrieval with no side effects. However, it does not disclose what happens on a missing/invalid ID, whether the call requires authentication or specific scopes, or how costly the 'include' expansion is. It adds the notion of 'full details' but no real behavioral context.

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

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

Two compact sentences with the core action and the optional expansion front-loaded in order of importance. Every clause earns its place; nothing is padded.

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

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

For a simple two-parameter read tool with a fully documented schema and no output schema, the description covers what the tool does and the optional expansion. It could say a bit more about the shape/scope of 'full details' and failure behavior, but nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the same example include values ('company,project_manager,workflow'). The description's mention of related resources duplicates rather than extends 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?

States a specific verb (Get) and resource (Productive.io project) and scopes it to a single record fetched by ID, which implicitly separates it from productive_list_projects and the create/update siblings. It stops short of naming an alternative tool or drawing the contrast explicitly, so it is clear but not maximally differentiated.

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

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

Usage is implied: fetch one project when you already have its ID. There is no explicit when-to-use vs productive_list_projects, no statement of prerequisites, and no guidance on when the 'include' expansion is worth requesting. Adequate but leaves routing to inference.

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

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

With no annotations, the description carries the disclosure burden. 'Get' implies a read-only lookup and it names the kinds of fields returned (description, dates, time tracking), but it says nothing about permissions, missing-ID error behavior, or whether includes affect cost.

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 with no filler; the resource and the ID requirement come first. It is appropriately sized for a simple lookup, though the trailing 'with full details...' clause is somewhat generic.

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 sketches the returned content (description, dates, time tracking), and both parameters are covered by the schema. Missing are edge cases like not-found behavior, but overall it is sufficient for calling a simple read tool.

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

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

Schema description coverage is 100%, so both 'id' and 'include' are already documented with examples in the schema. The description adds no further meaning beyond the fact that the lookup is ID-based, 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?

Specific verb and resource: 'Get a single task by ID from Productive.io'. Naming the ID-keyed, single-record scope implicitly separates it from productive_list_tasks, but it does not explicitly name or contrast with that sibling.

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

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

Usage is only implied by 'by ID' — the agent can infer this is for fetching one known task rather than browsing. There is no explicit when-to-use/when-not guidance and no mention of the list/update/create task siblings.

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

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

No annotations are provided, so the description carries the full burden. It adds genuinely useful domain context with the booking-method legend (1=per day, 2=percentage, 3=total hours), but says nothing about read-only safety, pagination behavior beyond the schema's page fields, or what a result record looks like.

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 resource and the filter dimensions. The trailing booking-method legend is somewhat orphaned since no parameter exposes it, costing a small amount of focus.

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 seven-parameter list tool with no output schema and no annotations, the description covers purpose and filters adequately but omits what the response contains, whether results are paginated by default, and any permission or scope constraints. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so every parameter is already documented and the baseline is 3. The description restates the filter dimensions and adds the booking-method enum mapping, but note that 'booking method' is not actually a filterable parameter here, so that detail is contextual rather than parameter-level 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 and resource ('List resource bookings/scheduling from Productive.io') and clarifies the dimension being retrieved ('who is booked and when'). It never differentiates itself from the closest sibling, productive_list_time_entries, which an agent could easily confuse with planned bookings.

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?

'Filter by person, project, or date range to see who is booked and when' implies the intended scenario but states no explicit when-to-use condition and names no alternative. The distinction between planned bookings and logged time entries is not drawn, leaving the agent to infer it.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses nothing about read-only safety, pagination behavior (despite page/page_size params), result limits, or required permissions, leaving real gaps for an agent to infer.

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

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

Three short sentences, front-loaded with the core action and scope, then filtering options, then the use case. No filler or restatement of structured fields beyond what is needed.

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 zero-required-parameter list tool with no output schema, the description covers purpose and filtering but omits pagination/sorting behavior and the shape of returned company records (including IDs it promises). Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all five params (page, sort, query, status, page_size) are already documented in the schema. The description restates the query/status filtering behavior but adds no syntax or format detail beyond it, matching the baseline.

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

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

States a specific verb and resource ('List companies (clients) in Productive.io') and clarifies the domain synonym 'clients'. It does not explicitly differentiate from the many sibling list tools or from productive_get_company, 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?

Provides a motivating use case ('find company IDs needed for creating projects or filtering deals'), which implies when to reach for it. However, it never names an alternative or a when-not-to-use condition, e.g. that productive_get_company is for a single known company.

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

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

With no annotations, the description carries the full burden, and it does add domain semantics (deal status codes, the budget/deal relationship). However, it omits useful read-operation context such as pagination defaults, result limits, or auth/permission requirements for a tool that returns a paged collection.

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 that are front-loaded with the purpose; the trailing sentence about budgets earns its place by clarifying terminology. 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 read tool with seven optional parameters and no output schema, the description establishes purpose and filters but says nothing about the shape of the returned collection (fields, pagination behavior, totals). It is adequate but leaves the response contract entirely unstated.

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 seven parameters are already documented in the schema, making the baseline 3. The description restates the deal_status legend (already in the schema) and adds nothing about sort, page, page_size, or the deal_type_id values.

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 (budgets/deals from Productive.io), and the final sentence clarifies that budgets are deals linked to projects, which disambiguates the two terms an agent might confuse. It does not explicitly name or contrast with the singular sibling get_deal, so it falls short of full sibling differentiation.

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

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

The description says what can be filtered ('Filter by project, company, or deal status') but never states when to use this list tool versus productive_get_deal or other list endpoints, nor any exclusions or prerequisites. Usage is only implied by the verb 'List'.

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

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

No annotations are provided, so the description carries full behavioral burden. It only says it lists types; it doesn't mention pagination behavior, whether results are filtered by default, or what fields are returned. For a read-only list tool with no annotations, that's a significant shortfall.

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

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

Two sentences, front-loaded with the core action and followed by the purpose. 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?

A filtered list tool with fully documented schema parameters; the description covers purpose and use case but omits pagination and default filtering behavior, which would help an agent 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 coverage is 100%, so the schema already documents page, status, page_size, and subsidiary_id. The description adds no parameter syntax or 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 (document types) and explains what a document type is (invoice template, locale, tax defaults). This distinguishes it from sibling list tools like productive_list_services or productive_list_tax_rates.

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

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

Explicitly says 'Use this when creating invoices to find the correct document_type_id', which names the downstream use case. It doesn't name alternatives or exclusions, but the context is clear for a discovery tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation, but the description does not disclose auth requirements, rate limits, pagination behavior, or response characteristics beyond what the schema already covers.

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 with the purpose front-loaded and a concise definition sentence that earns its place. There is no redundant or wasted text.

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

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

The description is largely complete for a simple list tool with 100% schema coverage: it names the resource, scope, and required identifier. It does not explain the shape of the returned attribution objects, but with no output schema and low complexity, this 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%, so the schema already documents all three parameters, including invoice_id and pagination controls. The description adds no parameter-specific meaning beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb ('List') and resource ('invoice attributions') scoped to a specific invoice, and clearly distinguishes from the sibling create/update/delete attribution tools. The parenthetical definition ('budget links') further clarifies the domain term.

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 indicates the tool is used for a specific invoice and implies when it is relevant, but does not explicitly state when to use it versus alternatives such as creating or retrieving invoice details. No exclusions or alternative-routing guidance is provided.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read-only operation, but the description says nothing about pagination behavior, result limits, default sorting, or what the response contains—all relevant given the page/page_size/sort parameters. This is a meaningful gap for a tool with zero 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?

Two tightly written sentences, front-loaded with the core operation before the usage scenarios. No filler or repetition; every sentence earns its place.

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

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

For a 9-parameter list tool with no output schema and no annotations, the description covers the what and some of the why but omits pagination limits, default ordering, and return shape. Adequate as a minimum-viable definition but not complete for the complexity involved.

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 every parameter is already documented in the schema with types, ranges, and examples. The description only restates 'optional filters' and adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (invoices) plus the source system (Productive.io), which cleanly distinguishes it from the singular productive_get_invoice. However, it never explicitly contrasts itself with the many sibling invoice tools (create/update/from_previous), so 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 second sentence gives concrete usage contexts: finding invoices for a client, filtering by status, and locating source invoices to clone. This is explicit when-to-use guidance, though it does not name alternative tools (e.g. productive_get_invoice for a single record) or state when this tool is the wrong choice.

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

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

With no annotations, the description must carry the full behavioral burden. It adds a useful domain insight—that line items determine the invoice amount via quantity × unit_price—but does not state the pagination behavior (page, page_size), authentication requirements, or the safe, read-only nature of the operation.

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, well-structured sentences with zero waste. The core purpose is front-loaded, and the secondary domain insight is succinctly appended.

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, three-parameter read tool with a fully documented schema and no annotations or output schema, the description covers the essential purpose. Its gaps are in behavioral disclosure (pagination, read-only nature) and usage distinction, which are minor but leave the description as adequate rather than 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 description coverage is 100%, so the schema already documents all three parameters (invoice_id, page, page_size) with clear semantics. The description only reiterates the invoice_id requirement and adds no new syntactic or format details beyond what the schema provides. 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 (List) and resource (line items) scoped to a parent (a specific invoice). Clear and distinct from siblings like productive_create_line_item or productive_delete_line_item, though it doesn't name them explicitly.

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

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

The tool's read-only listing nature and its required invoice_id parameter imply usage context. However, the description provides no explicit guidance on when to use this tool versus alternatives, and no exclusions are 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?

No annotations are provided, so the description carries the disclosure burden. It helpfully states the default page_size=200 and lists return fields, but omits other behavioral traits such as auth requirements, rate limits, or pagination behavior when the team exceeds 200 members.

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 efficient sentences, front-loaded with the purpose and return fields before the usage guidance. Every sentence contributes distinct information with no filler.

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

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

For a simple list tool with no output schema, the description usefully enumerates the returned fields and notes the default page size. The only gap is that pagination behavior for large result sets is not addressed, but this is minor given the schema and absence of complex 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 description coverage is 100%, so all six parameters are already documented in the schema. The description only restates the page_size default and does not add syntax, format, or filtering semantics beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List all team members in Productive.io') and immediately clarifies scope with the returned fields. It is clearly distinguishable from the single-record sibling productive_get_person by the word 'List' and 'all'.

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

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

Provides a concrete use case: finding person IDs for task assignment or time logging. It does not explicitly state when not to use it (e.g., use productive_get_person when you already have an ID), so it falls short of a full when/when-not/alternatives treatment.

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?

No annotations are provided, so the description carries the full burden. It implies a safe read via 'List,' but says nothing about pagination behavior, default page size, total counts, or what happens when filters match nothing. It adds the archived-status filtering nuance but leaves most behavioral traits undisclosed.

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, both front-loaded with the highest-value information (what it lists, what it filters, why you'd call it). 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 read-only list tool with fully covered schema and no output schema, the description covers purpose, filters, and downstream usage adequately. The only meaningful omission is pagination expectations, which the schema partially carries.

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 every one of the 7 parameters already documents itself, including the status and project_type_id value mappings. The description restates the main filter categories but adds no syntax or semantics beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb+resource (list/search Productive.io projects) and enumerates the filter dimensions (company, project type, archived status). It does not explicitly contrast itself with the sibling productive_get_project, but the list scope and ID-harvesting framing make its role readable.

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 concrete use case: find project IDs to feed into productive_list_tasks or productive_list_deals. That is clear positive guidance, but it never states when to prefer productive_get_project or productive_list_deals directly, so no exclusions or alternatives are covered.

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

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

No annotations, so the description carries the full burden. It discloses useful domain behavior (services belong to a deal/budget, billing type meanings 1=fixed, 2=time and materials, 3=not billable), but says nothing about pagination behavior or what a returned record contains. Adequate but not rich for an unannotated 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?

Four short sentences, front-loaded with the resource definition before the filtering and usage guidance. Every sentence carries information; only the billing-type enumeration could be seen as marginally tangential to listing.

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 fully documented parameters and no output schema, the description covers purpose, filtering, domain relationships, and a usage trigger. A brief note on pagination/return shape would make it complete, but nothing essential is missing.

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

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

Schema description coverage is 100%, so page, sort, deal_id and page_size are already documented. The description reinforces deal_id filtering ('Filter by deal/budget ID') and supplies billing-type value semantics, adding a little meaning beyond the schema but not parameter syntax or defaults. 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+resource ('List services (budget line items)') and defines the domain concept and its parent (belongs to a deal/budget). It does not explicitly distinguish itself from the similarly named sibling productive_list_line_items, which could confuse an agent choosing between 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?

Gives a clear context of use: 'Use this to find service IDs needed for logging time.' No explicit when-not or named alternatives, but the usage trigger is concrete and actionable.

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

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

No annotations are provided, so the description carries the full burden. It adds useful domain context (subsidiaries determine 'Bill From' on invoices), but says nothing about pagination behavior, permissions, or result ordering. As a read-only list tool these gaps are modest, but behavioral disclosure remains thin.

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 action and resource, then domain meaning, then the routing hint. No filler or repetition.

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

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

For a zero-required-parameter read-only list tool with fully documented params and no output schema, the description supplies the key missing piece: why an agent should call it (to obtain subsidiary_id for invoice creation). Only pagination/return-shape detail is absent, 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 page, status, and page_size are already documented in the schema (including the status enum values 1=active, 2=archived). The description adds no parameter-level detail beyond that, 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 (List) and resource (subsidiaries in Productive.io), then explains what subsidiaries are ('company entities' that determine 'Bill From'). No sibling tool lists subsidiaries, so it is clearly distinguishable.

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

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

Explicitly names the scenario for use: 'Use this when creating invoices to find the correct subsidiary_id.' This routes the agent well. It stops short of stating when-not to use it or naming alternatives, but no obvious competing sibling exists for this resource.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the status value encoding and the ID-discovery purpose, but says nothing about pagination behavior, default sort, result caps, or whether the operation is purely read-only. Adequate but with real gaps for an 8-parameter listing tool.

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

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

Three short sentences, front-loaded with the core action and no filler. Some content (status legend, filter list) duplicates the schema, which slightly dilutes the value-per-sentence ratio.

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 8-param list tool with no annotations and no output schema, the description covers filters and the ID-lookup purpose but omits return shape and pagination semantics that an agent needs to page correctly. Sufficient to invoke, thin for correct integration.

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 all eight parameters are already documented, and the description's status legend merely repeats the schema's own '1=open, 2=closed' text. Worse, it advertises filtering by 'board' even though no board parameter exists in the schema, which could send an agent looking for a nonexistent argument.

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?

Starts with a specific verb+resource ('List and filter tasks') and enumerates the filter dimensions, so the agent immediately knows this is a search/list operation rather than a fetch-by-ID. It does not explicitly name productive_get_task as the alternative, so it stops short of full sibling differentiation.

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

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

The closing sentence gives a concrete reason to pick this tool ('Use this to find task IDs and task_list IDs'), which is a clear usage context absent from many list tools. There are no explicit exclusions or when-not-to-use conditions, so it does not reach a 5.

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

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

With no annotations, the description carries the full behavioral burden; it implies a read-only list operation and explains the per-line-item application semantics, which is useful context. However, it omits pagination behavior, return shape, and any auth/rate-limit notes, leaving meaningful gaps for an annotation-free 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 sentences, each front-loaded and purposeful: identity, application scope, then usage. 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 simple read-only list tool with complete schema coverage, the description covers what it does, its domain semantics, and its intended use. Only return-format/pagination detail is absent, 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%, so the schema already documents page, status, and page_size in full detail. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List available tax rates in Productive.io') and adds scope ('applied per line item, not per invoice'), which helps distinguish it from invoice-level tools. It is clear and non-tautological, though no sibling tax-rate tool exists to be differentiated from.

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

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

Explicitly states when to use it: 'Use this to find the correct tax_rate_id when creating line items,' tying it to the create_line_item workflow. No exclusions or alternatives are named, but the context is concrete.

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?

No annotations provided, so the description carries the burden. It states that it returns individual entries plus a summary with total hours, which is helpful return context. However, it lacks details on pagination behavior, permissions, or rate limits. With zero annotation coverage, more behavioral detail would be expected, but the return format is a start.

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

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

Three sentences, front-loaded with the action, followed by filtering options and return details. No wasted words, and the date format note is concise and useful.

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

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

The description covers what the tool does, how to filter, and what it returns (entries plus summary). It doesn't explain pagination or sorting behavior, which are in the schema but could be relevant. Given no annotations and the presence of pagination parameters, adding pagination context would improve completeness, but overall it's sufficient for a list tool.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description adds only the date format for after and before, which is already in the schema descriptions. It doesn't add meaning beyond what the schema provides, but since schema does the heavy lifting, a 4 reflects that the description doesn't subtract value and clarifies the date filters.

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 (time entries) with the source system named. Clearly distinguishable from siblings like productive_log_time, which presumably creates entries.

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?

Describes filtering options but gives no explicit when-to-use guidance versus alternatives. Productive.io has other list tools and a log_time tool, yet the description doesn't say when to choose this list over other retrieval methods or when to avoid it.

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

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

With no annotations, the description carries the behavioral burden and does disclose non-obvious traits: that started_at/ended_at auto-calculates duration and renders the entry as a time block. It stops short of stating permission requirements, reversibility, or error behavior, leaving some gaps for a mutation 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?

Front-loads the core action and required params, then layers the duration-mode guidance and ID lookups. Every sentence adds actionable information with no filler.

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

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

For an 8-parameter mutation tool with no output schema and no annotations, the description covers the key decision (which duration mode), prerequisites, and ID resolution. It omits what a successful call returns and any permission/side-effect caveats, but is largely sufficient to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining that 'time' and 'started_at'/'ended_at' are alternative duration specifications rather than independent fields, plus the format expectations. This interaction is not fully conveyed by the schema alone.

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

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

Opens with a specific verb+resource ('Create a new time entry in Productive.io') and immediately scopes the required inputs. It is clearly distinguishable from the sibling list_time_entries, which only reads entries.

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

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

Gives an explicit rule for choosing between the two duration modes ('ALWAYS prefer started_at/ended_at when the user mentions start/end times') with concrete examples, and routes the agent to productive_list_people and productive_list_services to resolve IDs.

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?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral constraint (draft-only, non-finalizing), which is useful. However, it says nothing about partial vs. full update semantics, permissions, or what happens to omitted fields — significant gaps for an unannotated mutation 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 sentences, front-loaded with the core action. There is mild redundancy between 'Cannot be used to finalize' and 'not yet finalized,' but no wasted 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 no annotations and no output schema, the draft-only constraint is correctly surfaced, but the update mechanics (partial vs. full, required-field behavior beyond 'id', response format) are unaddressed. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description adds no parameter-level meaning (e.g., whether fields are optional partial updates), 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 and resource ('Update an existing draft invoice') and narrows scope to draft-only invoices, which implicitly distinguishes it from create_invoice and get_invoice. It does not name a sibling explicitly, but the draft constraint gives an agent enough to tell it apart.

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

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

Provides a clear when-not condition: 'Cannot be used to finalize an invoice. Only draft invoices (not yet finalized) can be updated.' This is genuine selection guidance. It stops short of naming alternatives (e.g., a finalize/send tool), so it is not a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does indicate the tool only works on draft invoices, which is useful context, but it omits whether updates are partial or full, whether unspecified fields remain unchanged, whether the line item must exist, and what happens on failure. For a mutation tool with no annotations, this is a moderate gap.

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

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

A single, front-loaded sentence that efficiently conveys the core action and scope. Every word earns its place with no redundancy.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description is minimally adequate. It mentions the draft-invoice constraint but lacks details on update semantics, error conditions, and permission requirements. The high schema coverage compensates for parameter documentation, but behavioral context remains thin.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description lists four updatable fields (description, quantity, unit_price, discount), which repeats what the schema provides and omits unit_id and tax_rate_id. No additional syntax or format details are added beyond the schema.

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

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

The description states a specific verb and resource ('Update an existing line item on a draft invoice') and enumerates the mutable fields. It is clear but does not explicitly distinguish itself from sibling tools like productive_create_line_item or productive_delete_line_item, aside from the implicit verb difference.

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 'existing' and 'draft invoice,' but there is no explicit guidance on when to use this tool versus alternatives such as creating a new line item or updating a non-draft invoice. No exclusions or prerequisites (e.g., required permissions) are given.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Update an existing project' implies mutation but does not disclose whether omitted fields are preserved or cleared (partial vs full replace), what permissions are required, whether the operation is reversible, or anything about the response.

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

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

Two short sentences, zero filler, with the core action front-loaded. The second sentence is a useful pointer rather than padding, though it is not strictly necessary for invocation.

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 no annotations and no output schema, the description is minimally adequate: parameters are fully covered by the schema and a pre-read workflow is suggested. It stops short of describing partial-update behavior or side effects, which an agent would need to call this safely.

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 4 clearly described parameters (id, name, project_type_id, project_manager_id), so the schema does the heavy lifting and the baseline is 3. The description adds no additional meaning about parameter formats or constraints beyond what the schema already documents.

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 ('Update') and resource ('an existing Productive.io project'), so the agent knows exactly what the tool mutates. It does not differentiate itself from siblings like productive_update_task, though the naming convention makes the target resource unambiguous.

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

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

The sentence 'Use productive_get_project first to see current values' gives a concrete pre-requisite workflow step, which is implied usage guidance. It does not say when to choose this over alternatives or what conditions make an update appropriate versus creating a new project.

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?

No annotations are provided, so the description carries the full behavioral burden. For a mutation tool it discloses nothing about permissions required, whether omitted fields are preserved (partial update) or cleared, whether closing a task has side effects, or whether changes are reversible.

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 action before the prerequisite. It is efficient and wastes no words, though it is arguably terse given the mutation semantics it omits.

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 schema fully documents the 7 parameters and there is no output schema to explain, but a mutation tool with zero annotations should say more about partial-update behavior and side effects. Minimum viable, with a clear behavioral 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%, so the schema already documents all 7 parameters including id, title, closed, dates, assignee_id and description. The description adds no parameter-level meaning beyond what is in 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?

States a specific verb and resource ('Update an existing task') and names the service (Productive.io), so the agent knows exactly what it does. It does not distinguish itself from the sibling productive_create_task or productive_delete_line_item, but the verb/resource pairing is unambiguous.

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

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

The only guidance is 'Use productive_get_task first to see current values,' which gives a useful prerequisite but no when-to-use/when-not conditions and no routing to alternatives for other task operations. Usage is implied rather than explained.

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