Policy Pal

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

With no annotations, the description carries the full burden and does so: it discloses caching ('may be served from an earlier reading'), the readAt recency signal, refusal behaviour for non-legal documents, the ~20,000-60,000 vs ~1,000 token cost profile, and the not_stated guarantee that prevents fabricated promises. It also warns that plain fetches of JS-rendered pages return empty shells silently — a failure mode an agent could not infer.

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

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

Front-loaded with purpose and output shape, then guarantees, then caching, then exclusions — a logical order with no filler sentences. It is longer than most single-parameter tools warrant, and the closing 'legal advice' line partly repeats the disclaimer already implied, but each block carries distinct 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 one-parameter tool with no output schema and no annotations, the description supplies the return contract (verdict, eight answers, up to five findings with quotes), the trust model (not_stated handling, verbatim quoting), and the caching/recency caveat. Nothing an agent needs to call it correctly or interpret the result 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?

Only one parameter at 100% schema coverage, so the baseline is 3; the description earns above baseline by reinforcing that the URL must be the published policy page rather than a homepage or a user-pasted document. It does not add URL format/normalisation details 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?

Names a concrete verb+resource ('Read one privacy policy or terms-of-service page') and specifies the exact output shape: a grounded verdict, eight fixed yes/no/partly/not-stated answers, and up to five quoted findings. It also positions itself relative to siblings by citing policy_changes_since and noting the fixed question set that makes reports comparable across services (compare_policies' territory).

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

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

Explicitly states when to use it over the obvious alternative ('Use this instead of fetching and reading the page yourself') and backs that with cost/context reasoning. It also lists concrete exclusions: non-legal documents, general summarisation, user-pasted documents, and legal advice, plus the condition under which to escalate to policy_changes_since.

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

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

With no annotations, the description carries the full burden and does so well: it enumerates the guarantees (identical questions, verbatim quote per answer, not_stated for silence, not_asked for unasked question types, no fabricated silences), states how non-comparable or unread documents are surfaced, and declares it will not produce scores or rankings. This is exactly the behavioral context an agent needs before invoking.

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 rationale, then guarantees, then exclusions — a logical order that respects the reader. It is somewhat longer than necessary, and the trailing fragment 'Automated reading of one document. Not legal advice.' is loosely attached, but no sentence is wasted.

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 and no annotations exist, so the description must cover behavior, exclusions, and result semantics — and it does, including what an answer looks like (quote-backed, not_stated/not_asked) and how incomparable documents are reported. An agent has everything needed to call this 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 100% for the single urls parameter, so the schema already documents the 2-5 https URL constraint and the same-kind-document guidance. The description adds the 'two to five services' phrasing but no format or syntax 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 precise verb and resource — answering eight fixed questions across two to five services — and immediately distinguishes itself from the sibling check_policy by naming it as the single-service alternative. An agent can tell this apart from policy_changes_since and check_policy 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 ('two to five services at once'), an explicit when-not ('Do not use this for one service -- call check_policy'), an expectation-setting exclusion ('Do not expect a score or a ranking'), and the rationale for using it over manual reading. Nothing 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?

With no annotations, the description carries the full behavioral burden and largely does so: it discloses that unchanged answers produce an explicit 'nothing to report', that a missing prior reading is stated explicitly rather than guessed, and that an unanswered question is labeled 'not compared' rather than 'not_stated'. Those are exactly the edge-case behaviors an agent needs, though it says nothing about permissions, rate limits, or latency.

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 core instruction is front-loaded and the edge-case behavior is valuable, but several sentences are rhetorical rather than operational ('You cannot do this yourself at any context size', 'A changed comma is noise'). They aid framing but inflate the description for a two-parameter tool.

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 and no annotations, the description must explain return semantics, and it does: unchanged answers, absent prior readings, and the not-compared/not_stated distinction. Combined with full schema coverage on both parameters, an agent has what it needs to call and interpret the tool, with only auth and rate-limit behavior 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?

Schema description coverage is 100%, so url and since are already fully documented, including the YYYY-MM-DD/ISO format and the meaning of the cutoff. The description adds the framing that the comparison is against 'what was true then' but no syntax or constraint 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 concrete verb and resource ('say what changed in a service's policy since a date') and narrows the output to 'changes to the eight fixed answers' rather than text edits, which is a meaningful distinction. It does not, however, name or contrast itself with the sibling tools compare_policies and check_policy, so the agent must infer which one to call.

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: 'You cannot do this yourself at any context size: it needs the earlier version of the document' tells the agent this is the tool for historical diffs, and the note about returning nothing to report sets expectations. But there is no explicit when-not-to-use and no routing to compare_policies or check_policy, which matters given how easily they could be confused with this one.

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