Bidsketch MCP by usefulapi

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds useful behavioral context by marking this as a WRITE operation and noting that it changes the proposal's price. It also explains the fee calculation behavior, though it does not cover permissions, side effects on existing fees, or response behavior.

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

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

The description is front-loaded with the WRITE marker and core action, followed by the essential pricing rule and endpoint. Every sentence contributes useful information without repetition or filler.

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

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

For a mutation tool with annotations and no output schema, the description covers the key behavior: it is a write, it affects proposal price, and fee-type-specific amount semantics. It could be more complete by mentioning custom fees, optional items, and error or permission behavior, but it is sufficient for correct invocation in most cases.

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 56%, and the description compensates for key gaps by explaining that fixed fees treat amount as a total while hourly, monthly, and yearly fees treat amount as per-unit and require quantity. It leaves custom fee behavior and several optional parameters such as category and optional unaddressed, but the critical pricing semantics are clarified.

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

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

The description uses a specific verb and resource: 'add a fee line to a proposal,' and adds scope with 'it changes the proposal's price.' It also includes the write nature and endpoint, making it clearly distinguishable from read/list fee tools.

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

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

It gives clear usage context for adding a new proposal fee and explains how fee type affects amount and quantity handling. It does not explicitly name alternatives like update_proposal_fee or create_fee, so the when-not guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the 'WRITE:' prefix and the POST endpoint add essentially nothing an agent did not already know. The description says nothing about ordering/append behavior of sections, whether the proposal must be in a draft state, or whether the new section is immediately client-visible — all real concerns for this mutation.

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 clauses, front-loaded with the write semantics and zero filler. The raw endpoint string is arguably redundant for an agent that only needs the tool name, but it costs little and confirms the REST operation.

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

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

For a 4-required-parameter mutation with no output schema and no annotations rich enough to cover side effects, the description should say what comes back (a new section id?) and any state prerequisites. It covers intent and target resource but leaves the agent guessing about the effect and result of the call.

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 75%: description, proposal_id, and sectiontype carry their own schema explanations including the opening-first / closing-last rule. Only 'name' is undocumented, and it is constrained (1–300 chars). The description's 'text section' phrasing does signal that fee content is not accepted here, a small addition over the schema, so the baseline 3 holds.

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

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

States a specific verb and resource: 'add a text section to a proposal', scoped to opening or closing. The 'WRITE:' prefix and endpoint reinforce it is a mutation. It does not explicitly separate itself from the similar-sounding siblings bidsketch_create_section (template-level section) or bidsketch_update_proposal_section, leaving an agent to infer the distinction from the name.

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

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

There is no when-to-use / when-not-to-use guidance and no mention of alternatives, despite three sibling tools touching sections. The only usage-shaped information ('as an opening or closing section') duplicates what the sectiontype enum already says in the schema rather than helping the agent choose this tool.

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

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

Annotations only say this is a non-read, non-destructive mutation; the description adds real value on top by disclosing the plan-based client cap and its HTTP 426 signal, plus the POST /clients.json endpoint. It omits duplicate-email behavior and permission requirements, keeping it below 5.

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

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

Three tight sentences with the WRITE marker and required fields front-loaded. The trailing endpoint string (POST /clients.json) earns little for an agent that already has the tool binding, but it costs only a few tokens.

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 15-parameter mutation with a nested object and no output schema, the description covers required fields and the quota error but says nothing about what comes back (e.g. the new client id) that the agent would need for follow-up calls. Adequate to invoke correctly, incomplete for the surrounding workflow.

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

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

Schema coverage is only 40% across 15 parameters, so the description must compensate — and it partly does by naming the three required fields and clarifying that a company name goes in `name` (resolving a real ambiguity in the schema's "full name or company name"). The other ~10 fields, including the nested other_contact object, get no description-level treatment.

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 client in Bidsketch") with a leading WRITE marker, which cleanly separates it from the get/list/update siblings. It stops short of naming those siblings explicitly, so a 4 rather than a 5.

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

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

Gives clear operational context: it is a write, the three required fields are named, and the plan-cap constraint (HTTP 426) tells the agent what failure to expect. It does not state a when-not condition or route to bidsketch_update_client / bidsketch_list_clients, so no exclusions are provided.

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

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

Annotations already establish write (readOnlyHint=false) and non-destructive behavior; the description reinforces this with the 'WRITE:' marker and adds genuine side-effect scope ('not added to any proposal'). It stops short of other useful behavior: whether a duplicate name collides, what the response contains, or how errors surface for a mutation.

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 the operation class first, then the resource, then the disambiguating scope note. Nothing is redundant and nothing could be cut without losing signal.

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 create endpoint with no output schema and 43% schema coverage, the description leaves the agent under-equipped: it does not say what is returned (e.g. whether the new fee's id comes back for later use in bidsketch_add_proposal_fee), nor explain the meaningful enum/quantity semantics. The type and scope are clear, but the call mechanics are not.

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

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

Schema description coverage is only 43% — name, amount, feetype, and category carry no schema descriptions at all. The description says nothing about any parameter: no guidance on the feetype enum values, what 'quantity' vs 'amount' mean together, or how 'custom' interacts with 'unit'. It neither compensates for the gap nor adds meaning 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?

Specific verb+resource ('save a reusable fee on the account') with an explicit scope qualifier that separates it from the proposal-fee sibling: 'it is not added to any proposal.' An agent can distinguish this from bidsketch_add_proposal_fee or bidsketch_update_fee without inspecting the schema.

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

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

The parenthetical 'it is not added to any proposal' implicitly tells the agent when this tool is the wrong choice, which is real usage signal. However, it never names the correct alternative (bidsketch_add_proposal_fee) or states prerequisites such as whether a fee must be created here before it can be attached to a proposal.

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

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

Annotations only establish readOnlyHint=false; the description goes well beyond them by disclosing that the result is a draft, that nothing is emailed to the client, and that plan caps can trigger HTTP 426. It also names the two concrete endpoints used, which is behavior an agent cannot infer from the schema.

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

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

Four dense sentences, front-loaded with the 'WRITE:' marker and the draft/non-sending fact, then template semantics, then the cap error. No sentence is redundant or restates the title.

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

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

For a 9-parameter mutation with full schema coverage and no output schema, the description covers side effects, template behavior, and a failure mode. The only gap is that it never indicates what comes back (e.g., a proposal id) for chaining into bidsketch_add_proposal_section.

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

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

With 100% schema description coverage, the schema already documents all nine parameters including tax/discount fractions and date format. The description only reinforces template_id's copy-sections-and-fees behavior and its provenance from bidsketch_list_templates, which is a minor addition over the schema text.

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 an explicit write verb plus resource ('create a proposal for a client') and adds the optional template variant. This is clearly distinguishable from bidsketch_update_proposal and bidsketch_get_proposal among the siblings.

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

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

States the condition that selects the template path ('optionally from a template (template_id from bidsketch_list_templates)') and clarifies the output state ('created as a draft; this tool does not send anything to the client'). It does not explicitly route the agent to bidsketch_update_proposal for modifying an existing proposal, so the exclusion is only implied.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the 'WRITE:' prefix and the POST endpoint are largely reinforcing structured data. The description does add a useful behavioral fact (the section is not attached to any proposal) but says nothing about permissions, whether the name must be unique, or whether category/description are optional.

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

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

A single compact sentence with the write indicator front-loaded and the critical scope caveat inline. 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 with no output schema and low schema description coverage, the definition covers intent and scope but leaves the parameter semantics and required-vs-optional structure entirely to the schema. Adequate but with clear gaps.

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

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

Schema coverage is only 25%, so the description carries most of the burden, yet it mentions none of the four parameters. It doesn't explain what 'sectiontype' (opening/closing) means in practice nor that only name and sectiontype are required while category and description are optional.

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

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

States a specific verb and resource ('save a reusable content section on the account') and immediately disambiguates scope with '(it is not added to any proposal)', which cleanly separates it from bidsketch_add_proposal_section. An agent can distinguish create_section from add_proposal_section without opening either schema.

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

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

The parenthetical clarifies the condition under which this tool is the wrong choice, implying add_proposal_section is the alternative for proposal-attached sections. It does not spell out that alternative by name or state prerequisites, so it falls short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main added value is the disclosure of what the response contains and the underlying GET /clients/{id}.json endpoint. It does not mention behavior on a missing or unauthorized id, nor any rate limiting, which is a real gap for a lookup 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?

Two short sentences with zero filler; the returned-field summary is front-loaded and the endpoint path is a compact trailing anchor. Nothing could be removed without losing information.

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

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

With no output schema, the description does the necessary work of listing the returned fields, which is what an agent needs to decide to call it. It is only slightly short of complete for lacking any note on not-found behavior or whether nested proposal data is included.

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

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

Schema coverage is 100% and the single parameter is fully documented there, including its provenance ('from bidsketch_list_clients') and positivity constraint. The description adds no format or sourcing 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 and resource ('Get one client') and enumerates the payload it returns (contact details, address, notes, secondary contact), which distinguishes it from the list/create/update siblings. It doesn't name an alternative explicitly, but 'one client' versus the sibling bidsketch_list_clients 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?

Usage is implied by the singular fetch semantics and the required client_id, but the description never says when to use this instead of bidsketch_list_clients or bidsketch_list_client_proposals. No exclusions, prerequisites, or error conditions 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?

readOnlyHint=true in annotations already establishes the safe-read profile, so the description's burden is lower. It adds the returned field set and endpoint, but says nothing about not-found/error behavior or whether fees can be missing, leaving behavioral 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 resource and returned fields. The endpoint path is slightly redundant but still earns its place by signaling a single-item fetch.

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

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

With no output schema, the description usefully enumerates the returned fields, and the read-only annotation covers safety. It omits error/not-found behavior, but for a single-param read that gap 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 coverage is 100% and the fee_id schema description is rich, referencing bidsketch_list_fees. The description's endpoint format '/fees/{id}.json' marginally reinforces that the id is a path identifier, 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?

Uses a specific verb (get) and resource (saved fee) and enumerates returned fields (amount, quantity, unit, description). The 'saved fee' framing distinguishes it from the proposal-fee siblings at a high level, though it never explicitly contrasts with bidsketch_get_proposal_fee.

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

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

There is no statement of when to use this tool versus bidsketch_list_fees or bidsketch_get_proposal_fee, and no prerequisites or exclusions. Usage is only implied by the resource name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the GET endpoint path and the shape of returned data, which is genuinely useful. It says nothing about auth/permission requirements, error behavior for a missing id, or response envelope details.

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

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

A single front-loaded sentence with the endpoint appended; no filler. The enumeration of returned fields is slightly list-heavy but every term maps to real payload content.

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

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

With no output schema, the description correctly compensates by naming the fields a caller will receive, and annotations handle the read-only trait. Only the sibling-routing and error-behavior gaps keep it from full marks for such a simple single-param 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% and the single parameter is fully documented in-schema (positive integer, sourced from bidsketch_list_proposals), so the baseline is 3. The description adds no meaning beyond what the schema already provides about proposal_id.

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

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

States a specific verb and resource ('Get one proposal') and enumerates the payload fields (status, client, currency, fee subtotals, tax/discount, settings, section/fee counts), which lets an agent distinguish it from the lighter lookups. It stops short of explicitly differentiating from near-siblings like bidsketch_get_proposal_content or bidsketch_get_proposal_stats.

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

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

Usage is only implied by the singular 'one proposal' and the '{id}' endpoint; there is no explicit statement of when to pick this over get_proposal_content, get_proposal_stats, or list_proposals. The schema's reference to bidsketch_list_proposals hints at the lookup flow but the description itself gives no routing guidance.

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

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

readOnlyHint=true already declares the safety profile, so the description's added value is the disclosure that content comes back in a defined order (opening sections, fees, closing sections), which is genuinely useful given there is no output schema. It stops short of describing response format, errors, or edge cases.

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

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

Two short sentences, zero waste, with the core purpose and content structure front-loaded. 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 single-parameter read tool with annotations covering safety and no output schema, the description gives enough about what comes back (ordered sections and fees) to call it correctly. Only a deeper return-format description would push this higher.

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

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

With one parameter and 100% schema description coverage, the schema fully documents proposal_id as a positive integer. The description adds nothing beyond that, so the baseline 3 applies.

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

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

The description names a specific verb (Get) and resource (full content of a proposal) and adds the ordering of the returned content. It implicitly separates itself from bidsketch_get_proposal (metadata) via the word 'content', but never names a sibling explicitly.

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

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

There is no when-to-use/when-not guidance and no named alternative. An agent must infer from the tool name whether to call this versus bidsketch_get_proposal or bidsketch_list_proposal_sections.

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

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

readOnlyHint=true already declares this is a safe read. The description adds the underlying REST path (GET /proposals/{id}/fees/{fee_id}.json), which is mildly useful for tracing behavior but says nothing about what a fee line contains, error cases, or permission needs.

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

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

Two short sentences, front-loaded with the purpose. The REST path is arguably redundant for an agent, but it is brief and does no harm.

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

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

With no output schema, the description could sketch what a fee line returns (amount, description, section linkage), and it doesn't. For a simple two-param read this is adequate to invoke but thin for interpreting the result.

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

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

Schema coverage is 100%, and both parameters already document themselves as positive integers. The description only mirrors them via the endpoint template ({id}, {fee_id}) and adds no semantics such as whether fee_id must belong to proposal_id.

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

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

States a specific verb (Get) and resource (one fee line of a proposal), which distinguishes it from list_proposal_fees and from the global get_fee. It stops short of naming those siblings, so an agent must infer the distinction from 'of a proposal'.

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

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

No statement of when to use this versus bidsketch_list_proposal_fees or bidsketch_get_fee. The word 'one' weakly implies singular lookup, but there are no explicit conditions, prerequisites, or alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the description does not contradict it. It adds that the section's HTML description is included (relevant since there is no output schema) and gives the endpoint path, but says nothing about error behavior for missing IDs or authentication. Meets the lower bar set by annotations without going far beyond it.

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, the purpose front-loaded and the endpoint path supplied as secondary detail. The path template is mild redundancy against the schema but costs little space.

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

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

A simple two-parameter read with fully documented schema and a readOnly annotation; the description fills the main remaining gap by telling the agent that the HTML description is part of the result. Missing only minor context such as behavior for an invalid or unknown section ID.

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 both integer parameters documented as positive integers, so the baseline is 3. The description only mirrors the schema's parameter names via the {id}/{section_id} path template and adds no format or lookup-hint detail beyond it.

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

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

States a specific verb and resource ('Get one section of a proposal') and names the returned payload ('with its HTML description'), which distinguishes it from list_proposal_sections and get_section. It does not explicitly call out which sibling is the alternative, so it falls short of a 5.

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

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

Usage is only implied: 'one section ... with its HTML description' suggests it is the call for retrieving a single section's rendered content rather than a list. No explicit when-to-use, prerequisites, or named alternatives are given, despite several closely related siblings (get_section, list_proposal_sections, get_proposal_content).

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower. The description does add that the result is account-scoped and is a single aggregate (total proposal count) rather than a collection, but it omits any auth/permission context and gives no indication of response shape beyond that one number.

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

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

One short sentence plus the endpoint path; the key fact (total number of proposals) is front-loaded and there is no filler. Slight redundancy with the title and the raw endpoint reference cost it the top score.

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

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

For a zero-parameter, read-only aggregate endpoint with no output schema, the description supplies everything needed to call it correctly: what it returns, that it is account-scoped, and the underlying operation. Nothing material 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is trivially complete. Baseline for a no-parameter tool applies.

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

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

Names the specific resource (proposal statistics) and clarifies exactly which statistic is returned — the total number of proposals — which cleanly separates it from list_proposals. It is a noun phrase rather than a verb+resource statement, and it never explicitly contrasts itself with the sibling list tools, so it stops short of a 5.

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

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

Usage is only implied: an agent can infer it should call this when it needs a count rather than a full proposal list, but the description never says when to use this over bidsketch_list_proposals or bidsketch_list_client_proposals, nor does it state any preconditions. No explicit alternatives or exclusions are given.

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

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

readOnlyHint=true already declares the safety profile, so the description's main added value is that the response includes the section's HTML description, which is genuinely useful. It says nothing about not-found behavior, permissions, or response shape beyond that one field.

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

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

Two short sentences, front-loaded with the resource and the meaningful payload note. The trailing 'GET /sections/{id}.json' restates the schema's only parameter and is largely 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 single-record read with one required param, full schema coverage, and a readOnlyHint, this is nearly sufficient: the agent knows what it fetches and that HTML is returned. Only edge behavior (missing id, error shape) is unaddressed.

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

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

Schema coverage is 100% and the single parameter's schema text already says it is a positive integer from bidsketch_list_sections. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one saved section') and adds that the HTML description is included, which distinguishes it from the list/update siblings in substance. It does not explicitly name bidsketch_list_sections or bidsketch_get_proposal_section as the alternative, so it falls short of a 5.

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

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

Usage is only implied: needing a single saved section by id. There is no explicit statement of when to prefer this over bidsketch_list_sections or bidsketch_get_proposal_section, and no prerequisites or exclusions are given.

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

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

The readOnlyHint annotation already declares this is a safe read. The description adds useful context by disclosing that the response includes saved sections and fees, but it does not discuss errors, permissions, or response completeness.

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

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

Two short sentences with no wasted words. The main purpose is front-loaded, and the endpoint is included as compact supplementary 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 simple single-resource read tool with no output schema, the description is mostly complete: it says what the tool fetches and what the template includes. A slightly fuller note on the response shape would be useful, but the core need is met.

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

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

Schema description coverage is 100%, and the template_id parameter is fully documented in the schema, including its source. The description adds no further parameter syntax or constraints, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: "Get one template." It also clarifies scope by saying it returns the saved sections and fees, which distinguishes it from the sibling list_templates 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?

Usage is implied: fetch a single template by id, with the schema noting the id comes from bidsketch_list_templates. However, there is no explicit when-to-use guidance or named alternative, so an agent must infer the workflow.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds value by naming the returned fields (status values Pending/Viewed/Accepted/Declined and a draft flag) and the underlying endpoint. It says nothing about pagination behavior, ordering, or what happens for a client with no proposals, so it adds context without being rich.

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

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

A single compact sentence with the scope restriction front-loaded, followed by the endpoint path. No filler, though the raw endpoint adds little for an agent that cannot call HTTP directly.

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

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

With no output schema, the description carries the burden of describing returns and does so only partially — it names status and draft flag but not the overall response shape (list vs. wrapper, pagination metadata). Annotations cover the read-only safety profile, so the remaining gap is moderate rather than critical.

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

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

Schema description coverage is 100% and all three parameters (client_id, page, per_page) are documented in the schema itself, including defaults and maximums. The description adds only the implicit note that client_id scopes the result and nothing about page/per_page, 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 (proposals) plus a clear scope restriction: proposals belonging to one client. It does not explicitly differentiate itself from the sibling bidsketch_list_proposals, which an agent could easily confuse it with, so it falls short of a 5.

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

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

Usage is only implied: the phrase 'of one client' suggests you should call this when you have a client_id rather than when you want the full proposal list. There is no explicit 'use this instead of bidsketch_list_proposals when...' guidance and no stated prerequisites besides the required 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?

The annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the field set returned and the underlying endpoint, but says nothing about pagination behavior, default page size, or limits beyond what the schema states. Added value is modest given annotation coverage.

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

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

Two compact, front-loaded sentences with no filler; the resource and returned fields come first. The trailing endpoint reference is slightly redundant for an agent but is cheap and potentially useful for API-aware callers.

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-param paginated list with a readOnly annotation and no output schema, the description compensates by naming the returned fields. The main gap is the absence of pagination context (how to page through results), which is left entirely to the schema.

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

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

Schema description coverage is 100%, with both page and per_page fully documented (defaults, maximums). The description adds no parameter detail beyond the schema, 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 ('List the clients') and clarifies what a client is ('people or companies proposals are prepared for'), which an agent could otherwise confuse with proposals. It enumerates returned fields (id, name, email, phone), making the shape concrete. Sibling differentiation from get_client/list_client_proposals is implied by 'list' but not made explicit.

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

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

Usage is only implied by the list-vs-get naming pattern shared with siblings like bidsketch_get_client and bidsketch_list_client_proposals. There is no explicit statement of when to prefer this over get_client or list_client_proposals, and no exclusions noted.

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

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

readOnlyHint=true already declares this is a safe read, so the burden is lower. The description adds genuine value by enumerating the returned fields (category, type, total), which matters because there is no output schema. It does not mention pagination behavior or result ordering, but the schema covers the paging 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 with the purpose and returned fields front-loaded and no filler. The raw endpoint reference is minor redundancy but arguably useful for debugging.

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

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

For a two-parameter, non-destructive list tool, the description covers what it returns and what it lists; paging is fully documented in the schema and safety in annotations. Only the absence of guidance on ordering or typical result volume keeps it from a 5.

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%: both page and per_page document defaults and maximums directly in the schema. The description adds nothing about parameters, 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 (reusable fees saved on the account), and adds the returned fields (category, type, total). The phrase 'saved on the account' distinguishes these reusable fee templates from proposal-attached fees, though it never names the sibling list_proposal_fees explicitly.

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

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

Usage is implied rather than stated: an agent can infer this is the fee-library listing, not the per-proposal fee listing, from 'reusable fees saved on the account'. There is no explicit when-to-use/when-not or named alternative, so the agent must reason about 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?

readOnlyHint=true already establishes the safety profile, so the description's added value is return shape: it discloses that each line carries type, totals and an optional flag, which matters because there is no output schema. It does not mention pagination behavior or ordering, but the schema covers paging.

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

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

One compact sentence front-loads the resource and its contents, followed by the endpoint. The endpoint reference is low value for an agent but costs little; nothing is wasted or buried.

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

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

For a read-only list tool with full schema coverage and no output schema, the description supplies the key missing piece (what each fee line contains). Ordering and pagination semantics are the only notable omissions.

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

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

Schema coverage is 100% and the single required proposal_id plus paging params are fully documented in the schema. The description's 'one proposal' reinforces the required id but adds no format or constraint detail 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 (List) plus resource (fee lines) scoped to one proposal, and names the returned attributes (type, totals, optional flag). This clearly separates it from siblings like bidsketch_list_fees (global fee list) and bidsketch_get_proposal_fee (single fee).

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 scope 'one proposal' implies when to use it, but there is no explicit guidance on when to prefer bidsketch_list_fees, bidsketch_get_proposal_fee, or bidsketch_get_proposal_content. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the returned field set and the underlying endpoint, but says nothing about pagination behavior or ordering, which matters for a list tool with page/per_page params.

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 resource and payload front-loaded; the trailing endpoint reference is marginally redundant but not wasteful.

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 of two optional paging params with no output schema, the description covers what is returned and its safety profile is carried by annotations. Only pagination/ordering expectations are left implicit.

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

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

Schema description coverage is 100% and both parameters carry their own defaults and limits, so the schema does the heavy lifting. The description adds no parameter semantics at all, making baseline 3 correct.

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 proposals') and enumerates the returned fields (name, status values, draft flag, dates), which gives an agent a clear picture of the payload. It does not explicitly distinguish itself from the sibling bidsketch_list_client_proposals, though 'all' implies scope.

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

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

Usage is only implied: 'all proposals' suggests use this for an unfiltered listing rather than the client-scoped sibling, but no when-to-use or when-not statement is given. An agent must infer the choice between this and list_client_proposals.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is limited to the endpoint path and the hint that sections are 'text' content of the opening/closing variety. It says nothing about ordering, what fields each section carries, or whether empty results are possible.

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 establishes the scope, followed by the endpoint as a compact reference. Nothing is redundant or padded.

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

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

For a simple paginated read with full schema coverage and no output schema, the description covers what is listed and against which proposal. The remaining gap is the shape of the returned sections, which matters somewhat since no output schema exists.

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

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

Schema description coverage is 100%, with page, per_page, and proposal_id all documented including defaults and bounds. The description only restates that the id is a path parameter, adding no semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the text sections of one proposal') and narrows the scope with '(opening and closing)', which separates it from the global bidsketch_list_sections. It never names a sibling tool explicitly, but the 'of one proposal' scoping makes the distinction inferable.

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

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

Usage is only implied by the resource name and scope; there is no statement of when to call this versus bidsketch_get_proposal_section (single section), bidsketch_get_proposal_content, or bidsketch_list_sections. The agent must infer the choice from tool names alone.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description usefully discloses that category and a type discriminator (opening/closing) come back, which annotations don't say. It adds no information about pagination defaults, ordering, or whether the list is scoped to the authenticated account only.

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 that states the resource and the returned shape, followed by the endpoint. The endpoint fragment is arguably filler since it restates nothing an agent can act on, but there is no real bloat.

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

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

For a low-complexity, zero-required-parameter list tool with no output schema and fully covered params, the description supplies enough: what is listed, what fields come back, and the read-only nature. The missing piece is disambiguation from the proposal-scoped sibling listing.

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?

Both parameters (page, per_page) are already fully documented in the schema at 100% coverage, including defaults and the 100 max, so the baseline is 3. The description contributes nothing about paging semantics, such as whether the section list is short enough to need paging at all.

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 plus resource: 'List the reusable content sections saved on the account', and it even names the returned attributes (category and type: opening or closing). It's clear what the tool does, but it never distinguishes itself from the close sibling bidsketch_list_proposal_sections (sections attached to a proposal vs. the account-level library), which is the one differentiation an agent actually needs here.

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

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

There is no when-to-use guidance: no statement of what it's for (browsing a content library before adding a section to a proposal), and no mention of when to use bidsketch_list_proposal_sections or bidsketch_get_section instead. The 'GET /sections.json' fragment implies a read but adds nothing about selection.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /templates.json), which is mildly useful, but says nothing about result ordering, payload shape, or what pagination returns beyond the schema's own notes.

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

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

Three short sentences, front-loaded with the action and scope, with zero filler. The endpoint reference is compact and the cross-reference is one clause.

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

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

For a simple two-optional-param read-only list, this is nearly complete: safety comes from annotations, parameters from the schema. Only the absence of any hint about result volume or paging behavior in practice keeps it from a 5.

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 and per_page are already fully documented with defaults and maxima. The description adds no semantics beyond that, which is acceptable at this coverage level but earns no extra credit.

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

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

Specific verb and resource ('List the proposal templates saved on the account') with scope made explicit (account-level), which cleanly separates it from bidsketch_get_template and the proposal-listing siblings.

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

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

Points forward to the consuming tool ('Use a template id with bidsketch_create_proposal'), giving the agent a clear reason to call this first. It lacks a negative/exclusion clause (e.g., 'use get_template for a single template's details'), so it stops short of a full routing statement.

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

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

Annotations already declare write and destructive behavior. The description adds meaningful partial-update semantics ('only the fields you pass are sent and overwrite the old values'), but does not mention irreversibility, permissions, or validation behavior for a destructive mutation.

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

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

Two compact clauses, front-loaded with the WRITE marker and the resource, followed by the key partial-update rule. 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 destructive mutation with 16 parameters, a nested object, no output schema, and incomplete schema descriptions, the description is too thin. It omits required client_id handling, response behavior, and meaning of most fields.

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

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

Schema description coverage is only 44% across 16 parameters, so the description must compensate. It explains partial-update semantics generally but gives no field-level meaning for undocumented parameters like city, phone, state, country, or the nested other_contact object.

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

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

States a specific verb (change fields), resource (existing client), and method (PUT /clients/{id}.json). The word 'existing' distinguishes it from bidsketch_create_client, though no sibling is named explicitly.

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

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

Implies usage through 'change fields of an existing client,' and the partial-update note helps, but there is no explicit when-to-use vs bidsketch_create_client or guidance on whether to fetch the client first with bidsketch_get_client.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered; the description adds genuinely new behavior: only supplied fields are sent (partial update, so omitted fields are preserved) and existing proposals retain their own copy. It stops short of stating irreversibility or permission requirements, but it clears the lower bar set by the annotations.

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

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

Three terse, front-loaded clauses — write intent, update semantics, proposal-copy caveat — with the endpoint last. Nothing is wasted and no sentence restates the title.

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

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

For an 8-parameter destructive mutation with no output schema, the description covers intent, partial-update behavior, side effects on proposals, and the transport endpoint — enough to call it safely. Gaps are minor: no mention of response content or whether renaming affects fees already attached to proposals.

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 75% and already documents fee_id, feetype, amount, quantity, unit and description. The description contributes the optionality contract ('only the fields you pass are sent'), which otherwise has to be inferred from the schema's single required field, though it adds no field-level detail beyond that.

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

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

States a specific verb and resource ('change a saved fee') plus the endpoint PUT /fees/{id}.json. The clause 'Proposals that already use it keep their own copy' implicitly separates it from the sibling bidsketch_update_proposal_fee, which edits the fee instance inside a proposal rather than the saved library fee.

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 'WRITE' marker and partial-update phrasing imply when to reach for this tool, but there is no explicit guidance on when to use it versus bidsketch_create_fee or bidsketch_update_proposal_fee, nor any stated prerequisites (e.g., fee must already exist).

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: passed fields overwrite old values, which clarifies the destructive semantics at field level (omitted fields are preserved). It doesn't cover permissions or failure behavior, keeping it below a 5.

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

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

Two compact sentences with the 'WRITE:' marker front-loaded so the agent immediately knows the operation class. The endpoint string is mildly redundant with the tool name but harmless; no filler.

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

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

With 9 params at full schema coverage and no output schema, the description covers the operation class and overwrite behavior adequately for correct invocation. It does not explain what a successful response contains or error conditions, 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% with formats, ranges, and per-field explanations (tax fractions, date pattern, currency pattern), so the schema does the heavy lifting. The description adds nothing parameter-specific beyond the overwrite note, 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 ('change fields of a proposal') and names the HTTP method/path. It does not distinguish this tool from sibling update tools like bidsketch_update_proposal_section or bidsketch_update_proposal_fee, leaving that differentiation to the name alone.

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 partial-update semantics ('only the fields you pass are sent and overwrite the old values') tell the agent how to call it, but there is no explicit statement of when to use this versus the sibling update_* tools for sections or fees, nor any prerequisite context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds the crucial PATCH semantics ('only the fields you pass are sent') and the underlying PUT endpoint, which tells an agent how to structure a safe partial update. It doesn't mention totals recalculation or other side effects, but the safety-relevant behavior is disclosed.

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 leads with 'WRITE:', then the effect, then the partial-update rule, then the endpoint. No 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?

For a destructive mutation the description covers input shape semantics and the endpoint, but omits what happens to proposal totals when a fee price changes and whether the change is reversible – relevant for a tool annotated destructiveHint=true.

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 80%, so most parameters (amount, feetype, quantity, optional) are documented at the field level. The description adds no parameter-specific guidance, which is acceptable at this coverage level, but doesn't earn extra credit.

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

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

States a specific verb ('change') and resource ('a fee line of a proposal'), immediately distinguishing it from read siblings and from the library-level update_fee. It doesn't name the sibling it supersedes, but the phrase 'fee line of a proposal' is precise enough to disambiguate.

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 'WRITE:' prefix and the 'only the fields you pass are sent' clause give clear context that this is a partial-update mutation on an existing fee line. It doesn't explicitly contrast with bidsketch_add_proposal_fee or bidsketch_update_fee, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds genuinely non-structured context: that only the supplied fields are transmitted and that they overwrite existing values, which tells the agent the operation is partial rather than full replacement. It does not state reversibility or permission requirements, keeping it below a 5.

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

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

One compact sentence plus the endpoint path; the mutation mode and overwrite semantics are front-loaded before the HTTP route. The raw endpoint adds marginal value for an agent but is not wasteful enough to drop below 4.

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 the description covers what is changed and how partial payloads behave, which is the essential part. It is silent on failure modes (invalid section_id), required permissions, and — since there is no output schema — what the call returns, leaving a meaningful 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?

With 67% schema description coverage, the schema already documents proposal_id, section_id, description and sectiontype. The description adds no field-level meaning and leaves 'name' and 'category' (which lack schema descriptions) unexplained. Baseline 3 is appropriate given the schema does most of the work.

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

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

The description names a specific verb (change/update) and a specific resource (a section of a proposal), and the 'WRITE:' prefix immediately signals mutation. It is distinguishable from sibling tools by scoping to a proposal section rather than a template section, though it never names update_section or add_proposal_section as alternatives.

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

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

The partial-update rule ('only the fields you pass are sent and overwrite the old values') is useful usage context for calling the tool. However, there is no explicit statement of when to use this versus bidsketch_update_section or bidsketch_add_proposal_section, and no prerequisites or exclusions are given.

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

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

Annotations already flag readOnlyHint=false and destructiveHint=true, and the description is consistent with that, adding two genuine behavioral facts: the update is partial (unpassed fields are untouched) and existing proposals retain their own copy of the section. It does not state irreversibility, permission requirements, or what an invalid section_id produces, which is notable given destructiveHint=true.

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 clauses with the WRITE marker and the partial-update rule front-loaded; nothing is wasted. The endpoint string is minor informational padding but adds no real cost.

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 destructive mutation with no output schema needs more: no mention of permissions/scopes, failure behavior for a bad section_id, or whether the change can be undone. The copy-on-write note is valuable, but the definition stops short of complete for a write tool carrying destructiveHint=true.

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

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

Schema coverage is 60% – section_id, description, and sectiontype carry their own descriptions, while name and category are bare. The description's 'only the fields you pass are sent' adds meaningful semantics about how optional params behave, but it does not compensate for the undocumented name/category fields beyond what their names imply.

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

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

States a specific verb and resource ('change a saved section') and front-loads the WRITE marker. The line 'Proposals that already use it keep their own copy' implicitly separates it from bidsketch_update_proposal_section, though that sibling is never named, so an agent must infer the boundary.

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

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

No explicit when-to-use / when-not statement and no named alternative among the many update_* siblings. Usage is only implied by the partial-update semantics ('only the fields you pass are sent'), which tells the agent this is a PATCH-style call but not when to prefer it over bidsketch_update_proposal_section.

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