terms

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

The annotations only provide generic hints (readOnlyHint: false, etc.), so the description carries the responsibility for behavioral disclosure. It clearly indicates a write operation ('Save') and adds valuable detail about the response, including the stored id, detected variables, and updated clause count. It does not discuss duplicate handling or quota failures, but the free-tier note appears in the schema.

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

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

The description is a single dense sentence with no wasted words. It front-loads the action and resource, then efficiently covers return value details that would otherwise be missing without an output schema.

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

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

For a tool with seven parameters and no output schema, the description plus the detailed input schema provide enough context to call the tool correctly. The description usefully fills the output gap by naming the returned fields. A small omission is the lack of guidance about alternative tools, but that does not block correct invocation.

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

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

Schema description coverage is 86%, and the schema already provides rich parameter explanations, such as {{variable}} placeholders, known category names, and auto-detection of variables. The tool-level description adds little parameter-specific meaning, but it does not need to because the schema carries the detail.

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 action verb ('Save') and identifies the exact resource: a reusable contract or proposal clause stored in a library. It clearly distinguishes this from sibling tools like clause_update and clause_delete, and from contract_assemble, by focusing on adding to the library.

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

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

The description implies the tool is for adding a new reusable clause, which is clear enough context. However, it does not explicitly state when to prefer it over alternatives such as clause_update for modifying an existing clause, nor does it mention any exclusions or prerequisites.

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

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

The annotations already declare destructiveHint=true, so the destructive nature is known. The description adds valuable context beyond that: it discloses that deletion is irreversible, that starter clauses are not re-seeded, and that the tool reports the remaining count. These specifics help the agent set expectations for the call outcome.

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

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

The description is two sentences with no redundancy. The primary action and input method are front-loaded, followed by the two critical warnings and the alternative tool. 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 destructive tool, the description fully covers what an agent needs: the input, the return behavior (reports count left), the irreversible nature, the non-reseeding caveat, and the alternative tool. With no output schema, the description adequately handles the response expectation.

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

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

The schema description for the 'id' parameter already states 'Clause id or exact title' with 100% coverage. The tool description merely repeats this phrase without adding new constraints, formats, or examples. Since the schema fully documents the parameter, a 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 action ('Delete one clause'), the resource ('clause'), and the input method ('by id or exact title'). It also differentiates from the sibling clause_update by explicitly naming it as the alternative for editing, so an agent can immediately tell this tool 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?

It gives explicit guidance: 'Use clause_update to change one you want to keep' – this is an explicit when-not and alternative. It also warns about the irreversibility ('There is no undo') and the non-reseeding of starter clauses, which informs when to use the tool cautiously.

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

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

The description states the tool will 'write the whole library to one file,' which is a side-effecting operation, while the annotation declares readOnlyHint=true. This directly contradicts the annotations, so the behavioral transparency score is the minimum per the rubric.

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

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

Three sentences, each adding useful information: what the tool does, the ordering/round-trip behavior, and the format restriction. The core action is front-loaded and there is no filler.

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

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

With no output schema, the description usefully discloses the return tuple (path, format, count) and the re-import behavior. It is mostly complete for a simple export tool, but the contradictory readOnlyHint creates ambiguity about side effects.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline applies. The description repeats the markdown/json pricing distinction already present in the schema and adds no meaningful parameter semantics 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?

The description uses a specific verb phrase, 'write the whole library to one file and return the path, format and count,' which clearly identifies the operation. It also distinguishes itself from the sibling clause_import by noting the export re-imports the same way.

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 explicitly opens with 'Call this tool to write the whole library to one file,' which gives clear guidance on the intended use. It does not explicitly list exclusions or alternative tools, but the purpose is well-scoped enough that an agent can infer when it applies.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral nuance beyond those annotations: the revision count 'stays 0 on free', and an ambiguous partial title match 'is refused with the candidates'. These are useful, non-obvious behaviors that help an agent predict outcomes. No contradiction with annotations exists.

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

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

Two sentences, no filler. The core action and lookup keys are front-loaded, and the second sentence covers the important edge case without over-explaining. Every clause earns its place.

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

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

For a simple read tool with two optional parameters, the description covers the return contents and the main edge case. The absence of an output schema is mitigated by listing the returned fields. The only minor gap is that neither parameter is formally required by the schema, so an agent might wonder what happens if both are omitted, but 'by id or title' strongly implies one is needed.

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 id and title individually. The description adds value by clarifying the relationship between the two parameters: they are alternative lookup keys ('by id or title'), and one can be partial while the other is exact. It also explains the consequence of an ambiguous title match, which the schema does not convey.

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

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

The description opens with a specific verb and resource: 'Return one clause in full by id or title.' It also enumerates what 'full' includes (body, category, tags, jurisdiction, variables, revision count), and the word 'one' distinguishes it from listing/searching tools. This is unambiguous and clearly separates clause_get from clause_list and clause_search.

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 makes the selection context clear: use this tool when you need a single complete clause and have an id or title. The partial-title refusal behavior also tells the agent how the tool behaves in ambiguous cases. It does not explicitly name alternatives like clause_list or clause_search, but the 'one clause in full' framing makes the intended usage evident.

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 provide broad hints (non-read-only, non-idempotent, non-destructive). The description adds genuine behavioral detail: duplicate titles are skipped unless overwrite is set, and the tool reports added/replaced/skipped/capped counts. This aligns with the annotations and goes beyond them.

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

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

Three short sentences, with the core action and results front-loaded. Every sentence adds information, though 'Free: 10 of your own' is telegraphic and could confuse an agent without more context. Still, the description is economical and well-ordered.

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 import tool, the description plus schema cover file formats, overwrite behavior, plan limits, and reported counts, which is enough for correct invocation. It lacks explicit error semantics and a full return shape, but the listed counts partially compensate for the missing output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents both path and overwrite. The description's 'duplicate title is skipped unless overwrite' and 'json is Pro' largely restate what the schema says, adding little new parameter-level meaning.

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

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

The description opens with a specific action ('load clauses from a .md or .json file') and names the observable outcome (added/replaced/skipped/capped counts). It is clearly distinct from siblings like clause_add or clause_export, but it never names those alternatives, so differentiation is implicit rather than explicit.

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

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

The first sentence explicitly tells the agent when to call it: to import clauses from a file. It also adds plan-level context (JSON is Pro, markdown works in free tier, 10-clause cap). However, it does not name alternative tools or state when not to use them.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the output field set, the sort order by category then title, and the relationship to contract_assemble. It does not mention pagination or exact-match semantics, but those are not critical for this simple read 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?

The description is a single dense sentence that front-loads the action and result fields, then provides ordering and routing guidance. Every phrase earns its place: output shape, sort order, category narrowing, and the clause_search alternative.

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?

This is a simple, one-parameter read-only list tool. The description covers the returned data shape, the optional category filter, the ordering semantics, and the sibling tool to use for word searches. There is no output schema, but the description itself supplies enough return-shape information for an agent to use the tool correctly.

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

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

Schema description coverage is 0%, so the description carries the burden for explaining the category parameter. 'Narrow with category' adds meaningful filter semantics beyond the bare string type in the schema, though it does not specify exact-match behavior or provide allowed values. Still, for a single optional parameter, this is sufficient 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?

The description names the verb 'List' and the resource 'the library', and explicitly enumerates the returned fields: id, title, category, tags, and variables. It also distinguishes itself from clause_search by noting that clause_search is for words, so an agent can tell the two apart without opening schemas.

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

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

The description gives clear usage direction: narrow with the category parameter, and use clause_search when searching by words. It also explains that the list ordering is the same order contract_assemble uses, which gives helpful context for when an agent should call this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: title/tag matches outrank body matches, jurisdiction filtering is free, and tag filters are skipped on free plans rather than causing an error.

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

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

Two sentences carry all the essential information: what is searched, how results are ranked, and which filters are free or Pro. There is no filler or repetition of schema details.

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

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

For a read-only search tool, the description covers the searchable fields, ranking, and filter behavior. No output schema exists, so return-value details are not specified, but the essential call semantics are clear. The only notable gap is the meaning of the category parameter.

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 documentation covers query, tags, and jurisdiction, while category has no schema description. The description enriches query semantics through ranking behavior and explains the practical effect of tag and jurisdiction filters. Category remains underspecified, but the overall parameter guidance is strong.

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

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

The description names a specific verb and resource: ranked search across clause titles, tags, categories, and bodies. It also distinguishes the tool by explaining ranking behavior, so an agent can tell it apart from clause_list or clause_get.

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 clearly implies a search use case, but it does not explicitly state when to choose this over clause_list or clause_get. It gives useful context about filters and Pro behavior, but no direct comparison with sibling tools.

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

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

The description adds meaningful behavior beyond the annotations by disclosing versioning behavior: Pro retains the previous text as a version, while the free tier applies changes without history. This is useful context that annotations do not convey.

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

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

Two tightly written sentences: the first states the core operation and target fields, the second adds behavior context. 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?

The description covers the main action and versioning behavior, but for an 8-parameter mutation tool without an output schema, it leaves out important guidance such as expected response, error behavior, or confirmation of success. Some parameters are also 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?

With only 13% schema description coverage, the description helps by naming several updatable fields (text, category, tags, variables, jurisdiction). However, it omits title and language parameters, so it does not fully compensate for the sparse schema.

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

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

The description uses a specific verb ('Change') and identifies the exact resource ('a clause') along with the editable fields. This clearly differentiates it from sibling tools like clause_add, clause_delete, and clause_get.

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

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

The description implies the tool is for modifying existing clauses, which is clear enough to distinguish it from clause_add or clause_delete. However, it does not explicitly state when to use this tool over alternatives or mention any preconditions or exclusions.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate a non-destructive write operation, which the description aligns with. Beyond annotations, it adds valuable behavior: omitted variables stay as bracketed prompts ('never invented'), clause_ids order equals document order, and the free-tier cap of 8 clauses. These are genuinely useful disclosures not present in structured fields.

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

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

Four tight sentences with the core purpose front-loaded, followed by two behavioral constraints (variable non-invention, ordering) and the tier limit. No wasted words; each 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 moderately complex tool (8 params, nested objects, no output schema), the description covers purpose, format, variable behavior, ordering, and usage limits. Schema handles parameter details. Minor gap: no statement about what happens on success/failure, but given 100% schema coverage this is not a serious omission.

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 8 parameters are already documented in the schema. The description reinforces the values/ordering behavior (already in the schema) and adds only the free-tier limit — marginal new value beyond the schema baseline of 3.

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 ('build') and resource ('a contract from library clauses'), with output formats specified. It clearly distinguishes from sibling tools, which are all clause-level operations (clause_add, clause_delete, clause_get) or license management — none assemble documents.

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?

'Call this tool to build a contract from library clauses' gives clear, direct invocation context. No sibling offers an assembly alternative, so explicit exclusion isn't needed; the guidance is unambiguous about when this tool applies.

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

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety 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?

The description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential information.

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

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

For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.

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

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

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in 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 uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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

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

The description provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of 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, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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

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

Two dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.

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

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

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description reinforces this with 'Reads only.' It adds behavioral value beyond annotations by disclosing that ambiguous title matches cause a refusal, which is not present in the structured metadata. This helps the agent anticipate error conditions.

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

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

The description is a single, front-loaded sentence that packs action, purpose, and a behavioral constraint with no filler. Every clause earns its place, and the critical workflow hint appears before the refusal caveat.

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 tool with one parameter and strong annotations, the description covers the core workflow trigger (before contract_assemble), the output concept (which variable is used by which clause), and a notable edge case (ambiguous titles refused). It does not detail return formatting or error handling for missing ids, but the tool's simplicity and annotation coverage make that gap acceptable.

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 clause_ids, so the baseline is 3. The description adds meaning by explaining the purpose of these ids ('the clauses you name') and by clarifying that titles are accepted but rejected when ambiguous ('a title matching several is refused'), which goes beyond the schema's 'Clause ids or titles.'

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: 'List every {{variable}} the clauses you name use, and which clause uses each.' It clearly differentiates itself from siblings like contract_assemble by referencing its role in gathering facts before assembly, and from clause_get/clause_list by focusing on variable dependencies rather than clause content.

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

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

The description gives clear context for when to use the tool: 'so the facts are gathered before contract_assemble leaves bracketed prompts.' It also notes a key constraint ('a title matching several is refused'). However, it does not explicitly name alternative tools or state when not to use this one, though the timing cue is strong enough for an agent to infer the intended workflow.

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