california-hoa-law

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine behavioral context beyond them: the result cap ('up to three articles'), the return shape (title, link, one-line topic), and a workflow obligation to preserve the haveny.co URL as a clickable markdown link rather than summarizing it away.

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 purpose, followed by trigger condition, return shape, and a flagged imperative. Every sentence does work, though the parenthetical topic list and the URL instruction make it slightly longer than the minimum needed.

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

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

There is no output schema, so the description must carry the return contract — and it does, specifying the cap of three items, their fields, and how to relay the URL. Combined with the usage trigger and annotation-covered safety profile, nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the single 'topic' parameter is already documented with the same example values the description paraphrases. The description adds little to the parameter's meaning 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 ('Find') and resource ('Haveny articles that cover a California HOA board topic'), and enumerates the covered topics in parentheses. It distinguishes itself from siblings thematically (board duties vs. homeowner rights/statutes) but never names an alternative tool, 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?

Gives a clear trigger condition: 'Use when the user is on a board or asking about board duties.' That is real routing guidance, but it offers no exclusions or named alternatives, so an agent working near get_homeowner_rights or lookup_hoa_statute gets context without an explicit boundary.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description goes beyond them by disclosing the output shape (up to three articles with title, link, one-line topic) and a critical behavioral quirk: the URL appears in the first line and must be relayed as a markdown link. That is real added value, though auth or rate-limit context is absent.

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

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

Front-loads what the tool does, then result shape, then the output-handling requirement — a logical order. It is a bit long, and the emphatic 'IMPORTANT... do not summarize it away' section is instructionally heavy, but it targets a real failure mode so it largely 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?

With no output schema, the description compensates by describing the return value (up to three articles, fields, first-line URL). For a single-param lookup tool with annotations covering safety, this is nearly complete; only the boundary with sibling knowledge/statute tools is left unstated.

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

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

There is a single parameter with 100% schema description coverage, including worked examples ('records request was denied', 'special assessment notice for $5,000'), so the schema carries the burden. The description reinforces the framing ('situation described from the homeowner side') but adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Find the Haveny articles') plus a precise scope: California HOA situations framed from the homeowner side, with concrete example situations. The homeowner perspective implicitly separates it from get_board_obligations and lookup_hoa_statute, but no sibling is named explicitly, so it lands at 4 rather than 5.

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

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

The parenthetical list (records request, election, special assessment, rule enforcement, unresponsive management) shows the intended situations, which implies when to use it. However, it never says when NOT to use it or explicitly routes the agent to lookup_hoa_statute/search_hoa_knowledge for statutes or general knowledge — the distinction is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world behavior, so safety is covered. The description adds genuinely new behavioral context: the tool returns a haveny.co article URL on its first line and instructs the agent to preserve it as a clickable link, which matters for downstream formatting. It does not cover pagination or error behavior, but those are less relevant here.

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

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

Three sentences, front-loaded with the core action and return contents, with the usage trigger second. The IMPORTANT block is somewhat emphatic and could be trimmed, but every sentence carries information.

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

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

With no output schema, the description carries the burden of describing return values and does so (heading, one-line description, article links) plus an output-handling instruction. For a single-parameter read tool with full annotation and schema coverage, nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100% and the parameter already documents both accepted forms (section number or topic) with examples. The description mirrors that (section number vs 'what a section is about') but adds no new syntax or matching rules 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 (look up) and resource (California Davis-Stirling Civil Code / Corporations Code section) plus what is returned (heading, one-line description, links to Haveny articles). An agent can distinguish it from search_hoa_knowledge or get_board_obligations without opening the schema.

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

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

Gives an explicit trigger condition: user mentions a specific section number (§5855, §5210) or asks what a section is about. It does not name which sibling to use instead when the query is topical rather than section-specific, so routing among alternatives is still partly inferred.

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

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

Annotations already declare this a safe, read-only, idempotent, closed-world read. The description adds genuinely non-obvious behavioral detail: the first line carries a haveny.co URL and the agent must relay it as a clickable markdown link. That output-handling contract is real value beyond 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?

Front-loaded with the core action, then the when-to-use rule, then the critical output instruction. Everything earns its place, though the final sentence is slightly long and the 'IMPORTANT' block could be tightened.

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 carries the return contract (count, fields, first-line URL) and adds a downstream-relay instruction. For a two-parameter read tool whose safety profile is covered by annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so 'query' (weighted over title, keywords, statute citations) and 'max_results' are already fully documented in the schema. The description adds no parameter detail; baseline 3 applies. Note a schema-internal oddity the description doesn't resolve: maximum=5 but max_results text and the description both cap at 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?

States a specific verb and resource ('Free-text search across Haveny's California HOA articles') plus the return shape (up to three articles with title, link, topic). The closing note also hints at the scope boundary relative to the statute/rights/obligations siblings, so an agent can distinguish it without opening a schema.

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

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

Gives an explicit when-to-use rule: broad questions or when no other tool fits. It stops short of naming the alternatives (lookup_hoa_statute, get_board_obligations, get_homeowner_rights) or stating when-not-to-use, which would make routing fully deterministic.

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