Opafex

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description needn't cover safety. It adds genuine behavioral detail beyond that: it returns best-fitting approaches with reasons, what to check first, a small first step, and remaining questions—helping the agent understand output shape even without an output 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?

Front-loaded with the core purpose, then usage triggers, then return content—well-structured and dense with no filler. Slightly long but every sentence 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 read-only analytical tool with 8 fully documented enum params and annotations covering safety, the description is largely complete. It describes what the output contains (approaches, reasons, checks, first step, questions), which compensates for the absent output schema. Only gap is per-parameter interpretive guidance.

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 every one of the 8 parameters has a rich enum description, so the schema already carries full parameter semantics. The description adds no parameter-level meaning at all—it doesn't explain how 'wand', 'prompting', or 'sector' map to the recommendation. Baseline would be 3 given full schema coverage, but the description's complete silence on params while claiming to 'map' inputs means it does nothing to help interpret them, so a 2.

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?

A specific verb+resource: it works out what a small business should automate first, from its current operations rather than a generic tool list. This is clearly distinct from siblings like estimate_automation_payback (calculation) and get_sector_playbook (reference).

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 names triggering situations (owner asks how AI can help, where to start, hype-vs-worth, getting people off admin) and instructs to map only what the owner said, excluding unstated items. This is real when-to-use guidance, though it doesn't explicitly name sibling alternatives.

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 adds value beyond them by disclosing the output nature — questions with reasons, ordered by relevance — and a legal-advice disclaimer, which an agent needs to frame the result.

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 scope, then usage triggers, then output shape. Dense but every sentence carries information; the long first sentence is the only mild readability cost.

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, but the description explains what comes back (questions plus reasons) and the non-advice caveat, and the input enums are fully covered in the schema. Sufficient for an agent to call and interpret it, though slightly more on ordering behavior could help.

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 enum values and their meanings fully documented in the schema, so the baseline is 3. The description only implicitly links 'that tool and that data' to the ordering, adding marginal meaning beyond structured fields.

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 checks) plus resource (UK GDPR checks before client/staff data goes into AI), and scopes it to UK firms with ordering by relevance. It is readily distinguishable from siblings like draft_ai_policy, which produces a document rather than a checklist.

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 rich, concrete triggers: an owner asking about ChatGPT, GDPR compliance of ChatGPT/Copilot, staff pasting customer details, or questions for an AI supplier. It lacks explicit exclusions or named alternatives (e.g. when to prefer draft_ai_policy), so it stops short of the top band.

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=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: what comes back ('the clauses and the steps to take before adopting it') and a scope limit ('A starting draft, not legal advice'). No contradiction with 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?

Three sentences, front-loaded with purpose before usage triggers and return value, and no filler. The final disclaimer sentence is short and load-bearing rather than padding, though the content enumeration in sentence one is somewhat list-heavy.

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 states what is returned and adds a legal-scope caveat, and annotations cover the read-only/idempotent profile. It stops short of explaining how the enum inputs shape the generated clauses or what the agent should do with the output next, which would complete the picture for a 4-parameter generation 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 description coverage is 100% and the enums are self-explanatory, so the schema already carries parameter meaning; baseline 3 applies. The description adds no syntax, format, or interaction detail about data, uses, teamSize or regulated that is not already 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?

States a specific verb and artifact ('Drafts a one-page AI use policy for a small UK firm') and enumerates the policy contents (approved tools, prohibited pastes, human checking, client disclosure, ownership). The resource is narrow and jurisdiction-scoped, so an agent can separate it from assess_automation_opportunities, estimate_automation_payback and get_sector_playbook 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?

Gives concrete triggering user intents: 'when an owner asks whether they need an AI policy, what to put in one, or how to stop staff pasting client details into AI tools.' That is clear when-to-use guidance, but it names no exclusion and does not point to check_ai_data_protection as the alternative for pure data-protection questions.

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), so the bar is lower. The description still adds real behavioral context beyond them: every assumption is stated, time for checking the output is deducted, and the agent is told to source inputs from the owner rather than invent them. It doesn't describe the numeric outputs in detail, which keeps it from a 5.

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 purpose before the usage triggers and the data-sourcing caveat. No filler or repetition. Slightly long for the value added, but each sentence carries a distinct 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?

No output schema exists, so the description must carry the return-value burden; it partially does by indicating that assumptions are surfaced and checking time is deducted, implying a payback/ROI style result. Combined with fully documented inputs, an agent has enough to call it correctly, though the exact returned metrics and units are not spelled out.

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 every one of the 6 parameters (including the enum for automatableShare) is already documented in the schema. The description only restates the parameter categories in prose ('owner's own hours, headcount, hourly cost and supplier quote'), adding framing but no semantics beyond the schema. 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+resource ('works out whether automating a task pays for itself') and enumerates the inputs it reasons from (owner's hours, headcount, hourly cost, supplier quote). This distinguishes it plainly from siblings like assess_automation_opportunities or get_sector_playbook, which are discovery/advisory rather than a payback computation.

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 trigger conditions: 'Use when an owner asks if an AI tool or automation is worth the money, how long it takes to pay back, or how to estimate the return before committing.' It also adds a data-sourcing instruction ('ask the owner for the numbers rather than guessing'). It does not, however, name a when-not boundary or point to a sibling alternative, so it stops short of a 5.

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=true, idempotent=true, destructive=false and closed-world, so the safety profile is covered. The description adds behavioral value by sketching the content of the returned playbook without an output schema, and by signalling that applicability is scoped to UK firms of a given sector.

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 purpose, then the trigger list, then the fallback in a short second sentence. Slightly redundant because the sector enumeration appears both in the description and the required enum, which is the only thing keeping it from a 5.

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, closed-world lookup with a fully documented single enum and no output schema, the description is complete enough: an agent knows what the tool returns and when to call it. It could add a hint about output depth or length, but nothing needed to invoke 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?

The single sector parameter is documented at 100% schema coverage, including the enum and per-value definitions, so the baseline is 3. The description restates the sector list in prose (accountancy, recruitment, law, insurance broking, property, construction, trades) but adds no mapping or nuance beyond what the enum description already supplies.

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 + resource ('Describes how a specific type of UK firm uses AI') and then enumerates exactly what the output covers (what gets drafted, chased or checked, what to look for in a tool, questions firms ask). It is instantly distinguishable from the siblings, which are all action/evaluation tools (assess, check, draft, estimate) rather than a reference 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 explicit trigger conditions by naming the roles and sectors that should call it (accountancy, recruitment, law firm, financial planning, insurance broking, estate/letting, construction, trades) and closes the loop with 'Use other for any other small business.' It stops short of routing to a sibling tool for out-of-scope callers, so it is clear context rather than full when/when-not/alternative guidance.

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