FixMyContract — contract clause information

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds real value beyond them: it enumerates the returned content (what the clause does, what to watch for, commonly asked for, CUAD v1 frequency) and states a scope limit. It does not mention any auth or rate constraints, but for a read-only lookup that is minor.

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

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

Front-loaded with the verb and resource, examples inline, and no filler. The closing scope sentence earns its place by preventing misuse. Slightly long with the parenthetical example list, but acceptable.

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

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

No output schema, so the description carries the return-value burden — and it does describe the glossary fields returned plus the frequency source. Combined with read-only annotations, an agent has enough to call it correctly. Only the frequency overlap with a sibling is left unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents the single 'clause' parameter fully (name or glossary slug, length bounds). The description's inline examples ('auto-renewal', 'indemnification', 'non-compete') add marginal clarity but largely restate the schema's own examples. 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: 'Returns the FixMyContract glossary entry for one clause type', with concrete examples of clause values. It is clearly distinct from list_clause_types (plural listing) and find_free_review_page. However, it does not name or contrast siblings, and its inclusion of frequency data slightly blurs the line with get_clause_frequency.

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 exclusion 'General information about the clause type, not an assessment of any particular contract' implies when to use it (informational lookup). But there is no explicit when-to-use guidance and no alternative named against get_clause_frequency, which also returns frequency data — an overlap the description does not resolve.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world. The description adds genuinely non-annotation behavior: that a no-argument call returns all pages, which is the tool's key fallback semantics. It stops short of describing link format or count, keeping it at 4.

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

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

A single sentence that front-loads the return value and folds the example enumeration and the no-argument fallback into the same clause. No waste.

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

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

For a one-parameter, read-only lookup with no output schema, the definition covers purpose, the argument, and the no-argument case; it also confirms the return is links. Only the count/format of returned links is left implicit, a minor gap.

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

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

Schema description coverage is 100%, so the single optional contract_type parameter is already documented. The description's examples (NDA, lease, freelance, employment) overlap the schema's own example and add only marginal breadth. Baseline 3 for a schema that does the heavy lifting.

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

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

States a specific verb and resource ('Returns links to the FixMyContract free review pages') and names the scope (per contract type, or all). No sibling tool (explain_clause_type, get_clause_frequency, list_clause_types) concerns review pages, so an agent can route to it unambiguously.

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

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

Clear context: call it with a contract type for that type's page, or omit the argument to get all of them. It gives the when-to-use-with-arg vs without-arg distinction but names no alternatives or exclusions, which the disjoint sibling set makes unnecessary.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower; the description still adds useful context: the exact dataset (510 CUAD v1 contracts), the provenance caveat ('as counted for the FixMyContract /data/cuad page'), and the default ordering when no clause is supplied.

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

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

Two sentences, zero filler, and the core behavior (what is counted) is front-loaded before the default-case behavior. Nothing extraneous.

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

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

With no output schema, the description carries the return-value burden and does so adequately by describing counts per clause type and the ordering of the all-categories case. It stops short of confirming the exact shape (single count vs. name/count pairs), which is the only remaining gap for a one-parameter read tool.

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

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

Schema coverage is 100% and it already documents the optional clause name, so the baseline is 3; the description goes one step further by defining what happens when the parameter is omitted (all categories returned, most common first), which the schema does not state.

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: it returns counts of contracts containing a clause type, over a named 510-contract CUAD v1 dataset. The purpose is concrete and clearly not the same as list_clause_types or explain_clause_type, though it never names those siblings to sharpen the contrast.

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 explains the no-argument path (return every clause category, most common first), which is genuine usage information, but gives no explicit when-to-use guidance or routing away from list_clause_types/explain_clause_type when the agent wants names versus counts.

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, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context beyond that: the exact fields returned and the intended chaining into explain_clause_type. It says nothing about ordering or pagination, but for a glossary enumeration that is a minor gap.

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

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

Two sentences, zero filler. The resource, returned fields, and filter are front-loaded before the downstream chaining instruction.

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

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

There is no output schema, so the description compensates by naming the returned fields (slug, name, category) and explaining how to use them. For a single-parameter read-only listing tool, an agent has everything needed to call it and act on 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?

With one optional parameter at 100% schema description coverage, the schema already documents 'category' with an example. The description restates the optional category filter but adds no syntax, matching rules, or case-sensitivity guidance beyond the schema.

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

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

States a specific verb (Lists) and resource (contract clause types) and names the exact fields returned (slug, name, category). It is clearly distinguishable from explain_clause_type, which consumes its output, and from the other frequency/page 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?

Gives clear usage context: it is the discovery step whose slugs feed explain_clause_type, and it notes the optional category filter. It does not state when NOT to use it (e.g. versus get_clause_frequency), so it falls short of fully explicit routing.

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