Plan Comply — SANS 10400 Building Plan Pre-Screening AI

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description earns credit beyond that by adding a concrete rate limit (60 req/min per IP), unauthenticated public access, and the shape of the response (status, matched records/metrics, canonical action URLs).

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 purpose and thresholds are front-loaded and useful, but the 'When to use' sentence is a tautology about executing this same tool, and the parameter enumeration duplicates the schema. Roughly a third of the text does not earn 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 carries the burden of describing the return, which it does reasonably well (structured JSON with status, metrics, action URLs). Safety, auth, and rate limit are all covered, leaving only minor gaps such as how optional parameters default on the server.

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 explains all four parameters including units (m²) and examples. The description only restates the parameter list with required/optional markers, adding no new semantic meaning — 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 (calculate SANS 10400-O natural lighting/ventilation compliance) with concrete thresholds (10% floor area, 5% openable sash), and scopes it to habitable rooms. An agent can distinguish it from the sibling calculators (stairs, municipal, pre-check) 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?

Names alternatives ('get_sans_rules', 'check_municipal_requirements', 'get_common_rejection_pitfalls') but only says to use them 'for their respective operations' — no condition that tells the agent when one actually wins. The positive guidance is circular: 'Call this tool when you specifically need to execute calculate_sans_fenestration.'

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?

Goes well beyond the annotations by disclosing rate limiting (60 requests/min per IP), unauthenticated public access, idempotency with zero state mutation, and the general shape of the response. These are exactly the operational details an agent cannot derive from readOnlyHint/destructiveHint alone.

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 standard and thresholds, which is good, but the labeled sections include filler: the 'When to use' sentence restates the tool name and the parameter list duplicates the schema. Roughly a third of the text does not earn 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?

There is no output schema, and the description does compensate with a return summary plus thresholds and side effects. However, for a compliance check the return description ('status, matched records or computed metrics') never says whether pass/fail violations and the governing clause are reported, which is the main thing an agent needs to interpret results.

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 each parameter already carries its constraint and required/optional status in the schema, so the description's parameter list is essentially a restatement. It adds no unit-conversion hints, interaction rules (e.g. how 2R+G is applied across riser/going), or default values for the optional fields beyond what the schema states.

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 ('evaluate stairway geometry and life safety') and pins it to a named standard (SANS 10400-M) with the actual numeric limits. This clearly separates it from sibling tools such as calculate_sans_fenestration or get_sans_rules without needing to open 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?

The negative routing ('do NOT use ... use get_sans_rules or check_municipal_requirements or get_common_rejection_pitfalls') gives real exclusions, but the positive guidance is circular boilerplate: 'Call this tool when you specifically need to execute calculate_stair_compliance'. It also omits the two most similar siblings, calculate_sans_fenestration and pre_check_building_plan, so the agent must infer how this differs from those.

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 open-world, so the description's job is to add context — and it does: 60 requests/min per IP rate limit, unauthenticated public access, and the shape of the JSON response. These are operational facts an agent cannot get from the annotation block 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 Behavior and Parameters sections are tightly front-loaded and earn their space, but the 'When to use' sentence contains a self-referential clause and a marketing domain reference (plancomply.co.za) that do not help tool selection. Roughly a third of the text is recoverable padding.

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 tool with no output schema, the definition covers selection, side effects, access constraints and return shape — enough to call it correctly. The only residual gap is the unresolved overlap with get_common_rejection_pitfalls, which the description lists both as content this tool returns and as a reason not to use it.

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 municipality parameter already documents accepted name and abbreviation forms with examples. The description only restates 'municipality (required)', adding no matching, fallback, or normalization semantics beyond the schema, so 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?

The first sentence gives a specific verb plus concrete resource list (checklists, Form 1/2 statutory forms, geotechnical/dolomite rules) scoped to South African metropolitan municipalities, so an agent can tell it apart from generic rule tools. The claim that it returns 'common rejection delay factors' while the usage section defers that topic to get_common_rejection_pitfalls slightly muddies the boundary.

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 three alternatives (get_sans_rules, get_common_rejection_pitfalls, calculate_sans_fenestration) and a 'do NOT use' condition, which is genuine routing guidance. However the positive 'when to use' clause is circular filler ('when you specifically need to execute check_municipal_requirements') and adds no selection criteria of its own.

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, and non-destructive, so the description earns credit for going further: 60 requests/min per IP rate limiting, unauthenticated public access, and an explicit zero-state-mutation statement. Those are real operational facts an agent needs for retry and throttling decisions. The return-value sentence is generic ('status, matched records or computed metrics') but acceptable.

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 lead sentence is strong and front-loaded, but the following text is template filler ('Behavior & Side Effects', 'Returns: Structured JSON object containing status, matched records or computed metrics') that reads as generated boilerplate. The circular 'when to use' clause occupies space without earning it.

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-optional-parameter read-only query with no output schema, the description covers access model, rate limits, mutation profile, and return shape. The only genuine gap is that it never explains how category filtering interacts with the 'top 25' cap, which could matter to an agent interpreting results.

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 category parameter has a fully enumerated value list with a documented default. The description only says 'category (optional)', adding nothing 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?

The first sentence gives a precise verb and resource: retrieving the top 25 municipal building-plan rejection reasons in South Africa with remediation steps. That is specific enough to separate it from get_sans_rules or check_municipal_requirements on subject matter. It stops short of a 5 because the differentiation is never stated in the purpose itself; it is only gestured at in the boilerplate 'when to use' sentence.

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 guidance is circular: 'Call this tool when you specifically need to execute get_common_rejection_pitfalls.' That tells an agent nothing about the decision. Sibling tools are listed, but only as names with 'for their respective operations,' so there is no condition under which any alternative should be chosen over this one.

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 description goes meaningfully beyond the annotations by disclosing a 60 requests/min per IP rate limit and public unauthenticated access, neither of which appears in the structured hints. It also confirms strictly read-only, idempotent behavior, though that duplicates readOnlyHint and idempotentHint rather than adding new information. The 'Returns' sentence is generic boilerplate ('matched records or computed metrics') and does not describe the actual pricing payload.

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 substantive purpose is front-loaded in one good sentence, but the remainder is template filler: the circular 'when to use' sentence, the 'Returns' sentence with no pricing-specific content, and redundant restatement of read-only/idempotent facts already in annotations. Roughly half the text does not earn its place for this particular 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?

For a zero-argument read-only query with full annotation coverage, the description supplies what an agent needs to select and invoke it, including auth and rate-limit context. The only gap is the generic return-value description that does not say what a credit-package response actually contains, which is a minor omission given no output schema exists.

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?

Zero parameters, so the baseline is 4, and the description correctly and explicitly states 'Parameters: none required (zero-argument query)'. There is nothing further to document.

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 first sentence names a specific verb and resource set: pre-submission plan audit credit packages, volume discounts, and checkout details. That distinguishes it well from the sibling tools, which are all technical/compliance calculators rather than commercial lookups. However, the purpose statement is undercut by the boilerplate framing that follows, which treats the tool as a generic query.

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 attempts an explicit when/when-not structure, but the positive trigger is circular: 'when you specifically need to execute get_credit_pricing' restates the name rather than describing a user need. The named alternatives (get_sans_rules, check_municipal_requirements, get_common_rejection_pitfalls) are dissimilar enough that the routing adds little. For a zero-argument pricing lookup, the implied usage is nonetheless clear enough to be minimally viable.

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 and destructiveHint=false, but the description adds genuinely non-redundant context: public unauthenticated access and a 60 requests/min per-IP rate limit. It also sketches the return envelope (status, matched records, canonical action URLs). The only gap is not saying how multiple filters combine (AND vs OR) or what an empty result looks like.

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 first sentence is well front-loaded, but the "When to use" boilerplate ("Call this tool when you specifically need to execute 'get_sans_rules' on Plan Comply SANS 10400 AI (plancomply.co.za)") is pure padding that consumes space without informing the agent. The Behavior & Side Effects and Returns sections are efficient.

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 0-required-parameter read-only lookup with no output schema, the description covers safety, auth, rate limits and return shape, which is largely sufficient. But the category vocabulary mismatch between description and schema, and the silence on whether sans_part and category compose or conflict, leaves an agent able to call it but not to predict filter behavior reliably.

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 query, category and sans_part, establishing a baseline of 3. The description merely restates that all three are optional and adds no semantics beyond the schema — and its category list actually conflicts with the schema's, which is a mild negative rather than added meaning.

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: search SANS 10400 clauses by Part (A–XA) or category, which an agent can distinguish from the calculate_* and check_* siblings. However, it undercuts itself slightly by listing categories ("Ventilation", "Stairs", "Documentation") that don't match the schema's category values ("Stairways", "Fire Safety", "Energy Efficiency"), so the resource scope is clear but the accepted values are muddy.

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 "When to use" sentence is circular filler — "call this tool when you specifically need to execute 'get_sans_rules'" tells the agent nothing. It does name three alternatives (check_municipal_requirements, get_common_rejection_pitfalls, calculate_sans_fenestration) but gives no decision criteria for choosing between them beyond "their respective operations", so routing still requires guesswork.

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 Behavior section adds real information beyond the annotations: a 60 requests/min per-IP rate limit and public unauthenticated access. The read-only/idempotent/no-mutation claims merely restate readOnlyHint, idempotentHint and destructiveHint, so they earn no extra credit. Nothing is said about how the optional parameters interact, what score scale is used, or how failures are reported.

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 sentence is well front-loaded, but the 'When to use' sentence spends words saying 'call this tool when you need to call this tool', and the parameters sentence duplicates the schema verbatim. The closing 'Returns' sentence is generic template text that also conflicts slightly with the specific outputs claimed in the first sentence.

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 an 11-parameter tool with no output schema, the description should carry more of the return-value and interpretation burden. It names the outputs (compliance readiness score, defect warnings, submission checklist) but doesn't explain the score's scale, what defects look like, or whether omitted optional fields are simply skipped in the check versus reported as unknowns.

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%, establishing a baseline of 3. The description only re-lists the parameter names (project_name, municipality, building_class, ...) without adding semantics, so it neither helps nor misleads beyond the schema, which already explains units, defaults and SANS context.

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 and resource ('run an automated multi-point regulatory validation on building plan specifications') plus the outputs, which is far more informative than the tool name alone. However, the sibling differentiation in the 'When to use' block is content-free boilerplate ('use ... for their respective operations'), so the agent learns the siblings exist but not what distinguishes them.

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 explained: the tool is for a full multi-point compliance pass, and the named alternatives (get_sans_rules, check_municipal_requirements, get_common_rejection_pitfalls) suggest this is the aggregate check. But the exclusion condition is tautological ('Do NOT use when another specialized tool fits better'), giving no actual decision rule such as 'use get_sans_rules to look up a single clause'.

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