movahedi.ca Privacy Data

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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral traits: results are verified against primary sources, jurisdictions without a fixed statutory period (Ontario private sector, BC PIPA) return an explicit 'no fixed period' rather than an invented deadline, and the tool never adjudicates the RROSH/serious-injury threshold. It also carries a data-minimization constraint (record IDs and statutory parameters only, no client names, narratives, or personal information) that an agent could not infer from annotations or 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 action, inputs, and output are front-loaded in the first sentence, and the constraints follow in a logical order. The middle stretch enumerating every statutory provision is dense and longer than needed for tool selection, but each clause is substantive rather than 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?

An output schema exists, so return formatting need not be described, and the description instead covers what matters for correct invocation: jurisdiction scope, risk-flag semantics, the honest no-fixed-period case, and the human-review boundary. Combined with a fully documented 4-parameter schema and read-only annotations, an agent has everything needed to call this safely.

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 baseline is 3; the description adds meaning above that for risk_flags by explaining they populate RROSH and serious-injury factors for human review rather than changing the outcome. Jurisdiction values are glossed by naming the underlying regime for each code, though lang and the discovery-date constraints are left entirely to 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 opens with a specific verb and resource: computing breach notification clocks for enumerated Canadian privacy regimes and returning statutory citations. It names the exact regimes (PIPEDA s. 10.1, Law 25 ss. 3.5-3.8, Alberta PIPA ss. 34.1/37.1, OSFI 24-hour advisory, AMF 24-hour regulation), which clearly separates it from sibling lookup tools such as canadian_privacy_consequential_action_lookup_v1 or privacy_law25_requirements.

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 states the required inputs (jurisdiction, incident discovery date, risk flags) and what the agent receives back, giving a clear usage context. It also sets an important boundary: risk flags assemble factors for human review and the tool never decides whether the threshold is met. What is missing is explicit routing versus alternatives (e.g. when to use privacy_law25_requirements instead), but the usage picture is otherwise clear.

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 closed-world, and the description does not contradict them. Beyond that it discloses the most decision-relevant behavior for an agent: unknown names return known: false rather than a guess, and first-party placement does not imply first-party data flow. It does not describe coverage limits of the underlying vendor database, which is the remaining behavioral 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?

The definition is well front-loaded: substance first, then the nuanced first/third-party example, then explicit use/do-not-use blocks. The only waste is mild redundancy between the opening sentence's 'Use this when someone asks...' and the later 'Use when:' line, which restate the same trigger.

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?

An output schema exists, so return fields need not be explained, and the description still previews them usefully; annotations cover the safety profile. Combined with the unknown-name fallback behavior, an agent has what it needs to call and trust the result. The one omission is how broad the vendor pattern coverage is, which affects when to distrust a known: false.

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 only parameter is documented with examples and a 'not a value, not a URL' clarification, so the schema already carries the semantics. The description adds only marginal framing (name-only identification, max one cookie) beyond that. Baseline 3 is appropriate when the schema 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?

The description names a specific verb and resource ('classify one cookie by name') and enumerates exactly what the classification returns: vendor pattern, receiving legal party, purpose, retention, control class. It also explicitly distinguishes the case an agent would find confusing (first-party set, third-party in substance, using _ga as the example), which separates it from a generic lookup.

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 an explicit 'Use when' with a concrete triggering question (who receives this cookie's data) and an explicit 'Do not use when' that routes to a named sibling, lookup_tracker, for browsing many cookies. The alternatives and the condition selecting them are stated, not 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 readOnly, idempotent, non-destructive, and closed-world, so the safety burden is largely carried. The description adds real context beyond that: results are paginated, and it enumerates the accepted operator/purpose/status value spaces. It stops short of describing result shape or how next_offset is returned, but with an output schema present that gap 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?

Well front-loaded: purpose and filters come first, then the exclusion, and every sentence is functional. Minor waste in the 'Use when' line, which restates the opening sentence's browse-by-operator-purpose-status framing almost verbatim.

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?

Six optional params with an output schema and full annotations mean the description doesn't need to explain returns. It covers purpose, filters, pagination, and the sibling alternative; the only real omission is the 'query' free-text search mode, which is a moderately important capability for an agent choosing this tool over lookup_crawler.

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 all six parameters are already documented, and the description's value lists (OpenAI/Anthropic/Google, training/search-index/user-triggered, active/retired/renamed) largely restate the enums. It never mentions the free-text 'query' parameter or limit/offset, so it adds little 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?

States a specific verb and resource ('List AI crawlers from the registry') plus the three filter dimensions, and explicitly distinguishes itself from the token-level sibling by saying not to use it when one exact token is named. An agent can route between list_crawlers and lookup_crawler from the description 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?

Has explicit 'Use when' and 'Do not use when' clauses, with the exclusion naming the concrete alternative behavior ('look that token up directly'). It also gives two motivating scenarios (comparing operator splits, pre-robots.txt audits) that tell an agent when this tool is the right entry point.

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 closed-world, so the description correctly does not waste space restating safety. Instead it adds genuinely new behavioral context: matching is case-insensitive but exact ("GPT does not match GPTBot"), which is the single most likely failure mode. It does not discuss what happens on a miss (null vs error), a minor residual gap; the output schema covers the success shape.

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 in a predictable order: capability, edge-case rule, then when/when-not routing. Every clause carries decision-relevant information and nothing is repeated from the annotations.

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?

Single required parameter, full schema coverage, an output schema for return shape, and annotations for safety profile — the description fills exactly the remaining gap (exact-match token semantics and sibling routing). Nothing an agent needs to call this correctly is absent.

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 baseline would be 3, but the description adds matching semantics the schema does not encode: case-insensitivity and the strict exact-match boundary with a concrete negative example. The schema supplies the "not a full user-agent string, not a URL" constraint, so credit is not double-counted.

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 ("look up one AI crawler or bot by its exact user-agent token") and unambiguously separates itself from list_crawlers, which appears in the sibling list. The enumeration of returned fields (operator, purpose, robots.txt behavior, docs) tells an agent exactly what answer shape to expect.

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?

Explicit "Use when" and "Do not use when" sections, with the exclusion naming the correct alternative (list_crawlers) for the list-shaped request. The routing decision is fully determined without inspecting sibling schemas.

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 establish that the operation is read-only, idempotent, non-destructive, and closed-world. The description usefully adds that results come from a knowledge base and are paginated, but offers little further operational context such as result ordering or behavior when all filters are omitted.

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 purpose is front-loaded, and the pagination note and usage exclusion are easy to locate. However, 'Use when: Use when' is redundant, and the searchable facets are repeated across the opening and usage-guidance sentences.

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?

Combined with the fully documented parameters, output schema, and safety annotations, the description provides sufficient scope, pagination context, and sibling routing for correct selection and invocation. Return-value details can appropriately remain in the output schema, and any omitted empty-query semantics are a minor gap for this simple search 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?

With 100% schema description coverage, the schema already documents the free-text query fields, substring vendor matching, result limit, and offset-based paging. The description largely repeats those search facets and does not add details such as how filters combine or whether an empty query browses everything, so it remains at the high-coverage baseline.

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 opening sentence gives a specific verb, resource, and searchable facets: searching the cookie and tracker knowledge base by cookie name, vendor, recipient organisation, or purpose. Concrete tasks such as finding a vendor's cookies or a tracker's data recipient, together with the classify_cookie comparison, clearly distinguish it from its most relevant sibling.

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 says to use the tool for pattern searches by name, vendor, or purpose and not to use it when someone names one exact cookie. The instruction to classify that cookie instead, reinforced by the earlier classify_cookie reference, provides an actionable alternative.

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 closed-world, but the description adds substantial behavior beyond them: quota accounting ('every operation counts as one call against the daily quota'), failure isolation ('a failing operation returns its error in place without aborting later independent operations'), and cross-operation data flow via $ref. These are exactly the operational traits an agent needs before composing a multi-step plan.

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 core behavior, then chaining, then failure semantics, then usage rules — a sensible order with no filler. Minor redundancy in the 'Use when: use when...' / 'Do not use when: do not use...' phrasing costs it a point, 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?

For a batching orchestrator with an output schema already present, the description covers everything an agent needs: allowlisting, operation count cap, quota cost, $ref chaining, partial-failure behavior, and when to prefer single tools. Return-value shape is correctly left to the 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 baseline is 3, but the description adds genuine meaning the schema does not: the $ref syntax '$ref:<operation-id>:<field>' is spelled out along with its semantics ('take a value from an earlier operation's first result'), whereas the schema only says a $ref string is allowed. It also summarizes the shaping options (select, filter, sort, limit, count_only) and the allowlisted GET path constraint, though it does not elaborate on filter operator behavior.

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 opening sentence states a specific verb and resource ('Run several read-only privacy API operations in one call') and immediately contrasts it with the alternative pattern ('instead of many single-tool calls'). An agent can distinguish this batch tool from siblings like privacy_get_enforcement_case or privacy_search_api without opening any 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?

Explicit when/when-not guidance is present: 'use when a question needs several lookups' and 'do not use for a single lookup; call the native tool directly.' This names both the selecting condition and the alternative tool class, leaving nothing 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, closed-world behavior, so the safety profile is covered. The description adds useful context beyond that: the tool returns a complete single record including penalty and the official regulator source link, and expects an ID obtained from a prior search. No auth or rate-limit notes, but none are needed at this level.

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 and return payload, then the routing rules. The 'Use when' line mildly repeats the preceding sentence about case IDs, but overall it is tight and readable.

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 lookup with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: the action, the expected ID provenance, the workflow position after search, and the shape of the result. No material 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 100% with a regex pattern and an example ID, and the schema field text already says the ID comes from a search result. The description's mention of the ID and a sample value ('cai-2026-05-06-openai') largely restates that, so it adds little meaning beyond the schema — 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 the full record of one privacy enforcement action by its ID') and enumerates the payload fields (summary, outcome, penalty amount, source link). It is clearly distinguished from privacy_search_enforcement_actions, which returns many cases rather than one.

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 'Use when' condition (a case ID is known and one full case is wanted) and an explicit 'Do not use when' condition (searching by topic), naming the sibling tool to use instead. Routing 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds what the annotations cannot: that the payload is a curated set of concrete requirements rather than source documents or a case lookup, plus the topical scope of that content. It stops short of saying whether the checklist is static reference content or reflects a specific version/date of the law, which is the one behavioral detail an agent might still want.

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 content scope is front-loaded well, but the second paragraph is largely redundant: 'Use this when someone asks what Law 25 requires' repeats the first sentence almost verbatim, and the 'Use when:' / 'Do not use when:' scaffolding produces duplication rather than added signal. Only the PIPEDA exclusion in the final line is genuinely new 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-optional-parameter read tool with a full output schema and complete annotation coverage, the description supplies everything needed to select and invoke it correctly. The only residual gap is whether the checklist is version-pinned reference material, a minor omission given the tool's simplicity.

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 'category' parameter carries its own description and a ten-value enum, so the schema does the heavy lifting. The description adds only a light restatement ('Optionally filter to one category like Consent or Incident response'), which confirms the filter is optional but contributes no new semantics about enum values or default behavior — baseline 3 fits.

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 concrete verb and resource — 'Get the Quebec Law 25 compliance checklist' — then enumerates the substantive areas covered (privacy officer, consent, cross-border transfers, breach notification, minors' data, automated decisions, complaint paths). That enumeration lets an agent judge topical fit without opening the schema, and the PIPEDA exclusion separates it from the federal-privacy 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?

It gives explicit positive triggers ('what Law 25 requires', 'how to comply', 'gap-assessment checklist') and an explicit negative case ('Do not use when someone asks about a federal PIPEDA term or case alone'), routing that traffic to the enforcement-action and glossary siblings. Both when and when-not are stated outright.

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, and the description adds real value beyond them: it instructs LLM clients to prefer this over pre-training memory, tells them to pin corpus_version in the answer, and discloses the French fallback path with the specific french_completeness_status 'partial_marked'. The one gap is that it never characterizes the shape of the definition returned beyond 'plain-language', though the output schema carries that.

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, then LLM-client guidance, then a Use when / Do not use when block — easy to scan. The trailing 'Use when' line restates the opening sentence almost verbatim, which is mild redundancy rather than noise.

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?

Given a two-field schema, full output schema, and clean annotations, everything an agent needs is present: what the tool returns, how to obtain a valid slug, when to prefer it over memory, and how language fallback is signalled. No material gap remains.

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 are documented, so the baseline is 3. The description still adds the slug convention and a concrete example ('law-25'), plus the caveat that some terms have first-class French and others are machine-marked partial — the latter partially restates the schema's lang description but sharpens the consequence of the choice.

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 ('look up the plain-language definition of a privacy or data-protection term') and scopes it to Canadian privacy with concrete examples. It also names the discovery sibling privacy_list_glossary_terms and contrasts itself with enforcement lookup, so an agent can pick it out of the 11-sibling list 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 positive trigger ('whenever someone asks what a term means', 'precise definition before answering'), an explicit exclusion ('Do not use when someone asks about a fine or case; use enforcement search instead'), and routes slug discovery to privacy_list_glossary_terms. Both a when and a when-not with a named alternative are present.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context, that results are 'scored deterministically with no model call' and that each hit carries method, path, summary, parameters, use-when/do-not-use guidance and an example query. That goes beyond the annotations, though it does not discuss result limits or empty-result 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 purpose and examples are front-loaded and the size is reasonable. There is some redundancy, since 'use when unsure which operation fits a question' is stated in the opening sentence and repeated verbatim in the 'Use when:' clause, and the phrasing 'use when: use when' reads awkwardly.

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 read-only discovery tool with a full schema, complete annotations and an output schema, the description covers purpose, selection criteria and result shape. The only minor gap is guidance on what an empty or low-confidence match means.

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 both parameters are already documented, and the description correctly reinforces that the input is a plain question rather than an endpoint or keyword syntax. It adds the expectation that the returned entries carry actionable detail, but says nothing additional about the limit parameter.

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 ('Search the movahedi.ca public API') plus the key qualifier 'by plain question, without guessing an endpoint,' and supports it with concrete example questions. That framing distinguishes it from the sibling lookup tools, which target a single known domain object.

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 explicit when-to-use ('use when unsure which operation fits a question; search first, then call the best match') and explicit when-not-to-use ('do not use when the right operation is already known; call it directly'). The alternative behavior is named, not merely 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, idempotentHint, non-destructive and closed-world, so the safety profile is covered; the description adds real value beyond that by naming the covered regulators, noting results carry plain-language summaries, penalties and official source links, and explaining the follow-up call pattern. It stops short of stating data coverage limits (earliest available year, how complete each regulator's corpus is) or result-count/pagination behavior, which are the remaining unknowns for a search 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?

Front-loaded with the resource definition, then examples, then return shape, then routing — a sensible order with no filler. The 'Use when' line partially restates the opening paragraph's list of triggers ('fines, enforcement cases'), a small redundancy, but the structure remains scannable.

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?

An output schema exists, so return values need not be explained, yet the description still summarizes them usefully and names the natural follow-up tool. What's missing for a search tool of this complexity is behavior on empty result sets and whether paging totals are exposed; the schema's offset description covers paging mechanics, so the gap is minor rather than disqualifying.

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 each parameter is documented in-schema, so the baseline of 3 applies. The description adds example query strings that illustrate free-text usage, but it never mentions the year or regulator filters, which are the two parameters most likely to change agent behavior; notably the schema's year bounds (minimum 2000, maximum 1970) are self-contradictory and the description offers no compensating 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?

States a specific verb (search) and resource (verified Canadian privacy enforcement actions) and scopes it precisely to CAI orders under Quebec Law 25 and OPC findings under PIPEDA. It explicitly positions itself as the entry point versus the sibling privacy_get_enforcement_case, so an agent can distinguish the two 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?

Contains explicit 'Use when' and 'Do not use when' sections, gives concrete trigger questions ('Has the CAI fined anyone for facial recognition?'), and routes the agent elsewhere for terminology lookups. It also states the two-step workflow: search here for a case ID, then call privacy_get_enforcement_case for details.

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