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

Annotations already carry readOnly/idempotent, but the description adds substantial behavior beyond them: the `complete` flag semantics (engine reads only first 501 entries), `groupsTruncated` meaning vs whole `total`, and the admin-only default 'Everything' listing constraint. These are non-obvious operational traits an agent needs.

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 and the routing sentence; the query-parameter equivalence paragraph is slightly longer than needed but earns its place by reducing invocation errors. Generally efficient, though dense across four paragraphs.

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 fully by describing the return shape (groups, values, total, complete, groupsTruncated) and where figure semantics come from (get_module_schema). Nothing essential to calling or interpreting it 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 coverage is 83%, so baseline 3, but the description adds real value: it declares the query params (module, listing, state, search, filters) are identical in name/meaning/access to list_entries', telling the agent how to populate them. It doesn't detail `top`/`breakdown` interaction 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 precise verb+resource: aggregation (count/sum/ave/min/max) over 'the entries list_entries would list', immediately disambiguating scope against a specific sibling. The 'Totals without paging rows' opening makes the operation's nature unmistakable.

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 routes intent: 'Use it for how many / how much / total / average / top N / per month questions instead of adding up list_entries pages.' Names the alternative and the condition that selects this tool, clearly a strong when-to-use directive.

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 is not read-only, not idempotent, and not destructive; the description adds real behavioral detail on top: the server verifies the object in S3, the exact return shape, and the 400 failure condition. It does not say what happens on repeat confirmation, 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?

Two tight sentences, front-loaded with the trigger condition, then the return contract and the failure mode. Every clause 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?

There is no output schema, and the description compensates by spelling out the returned { url, filename, mimeType, size } and explaining that url is the /s/ path usable as a File/Image field value. Combined with the 400 error case, an agent has everything needed to call and interpret 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 coverage is 100%, so both s3Key and workspaceId are already documented in the schema, including the workspaceId env/stateless fallback. The description adds no extra syntax or format meaning 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?

Specific verb (confirm) plus resource (a presigned upload) and the precise precondition (the PUT to uploadUrl succeeded). It is clearly distinguishable from request_upload_url and upload_file among the 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?

The description states the exact moment to call it ('after the PUT to uploadUrl succeeded') and warns to ensure the PUT completed first. It does not explicitly contrast with the sibling upload_file path, so it stops just short of naming 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 declare this is a non-read-only, non-idempotent, non-destructive, closed-world write, so the safety profile is covered. The description adds real behavioral context beyond that: role-based authorization, self-validating semantics that return structured errors 'without creating anything', and a pointer to the design-rules resource. It still doesn't describe the success payload or any rate/side-effect limits.

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?

Four sentences, front-loaded with the core action, then mode support, then prerequisites, then the validation/alternative nuance, ending with a resource pointer. Every sentence carries distinct information with no repetition of the name or title.

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 9-parameter tool with deeply nested objects and no output schema, the description covers purpose, authorization, validation behavior, and where the design rules live, which is close to sufficient. The remaining gap is the success response shape (e.g. whether a module id is returned) and workspace-scoping expectations, which are only partially inferable from the 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 already 89%, so the baseline is 3, but the description adds the key cross-parameter insight: which parameter families apply to workflow modules versus record list modules, and that field types/color rules live in inistate://schema/configure. That conditional-mode framing is meaningfully more than 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 ('Create a new module') and immediately scopes it into its two supported flavors: workflow modules (states, activities, flows) and record list modules (fields only). This lets an agent tell it apart from update_module and design_workflow 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 clear operational context: required roles are named, and it explicitly routes the validate-then-create decision by saying internal validation mirrors validate_design and that a separate validate_design call is optional. It does not say when to prefer this over sibling design_workflow or when creation is inappropriate, so it stops short of full when/when-not guidance.

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. The description adds value by disclosing resource loading (inistate://schema and inistate://design-guide) and the pipeline nature, which are not conveyed by 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 with no redundancy: first states purpose, second gives usage trigger, third provides pipeline and prerequisites. Every sentence adds unique value and is front-loaded.

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 no output schema, the description explains the output type ('scaffolded ModuleSchema template') and its role in a larger workflow. Resource loading and pipeline context provide sufficient completeness for agent invocation.

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?

Input schema descriptions cover both parameters fully (100% coverage), but the tool description enhances them by specifying the industry mapping behavior and providing detailed guidance on what to include in the 'description' parameter, plus resource loading instructions that affect parameter usage.

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 explicitly states it generates a 'scaffolded ModuleSchema template' from natural language, uses a specific verb ('Generate'), and distinguishes from siblings by outlining the workflow pipeline (design_workflow → validate_design → create_module → get_module_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?

Clearly says 'Use when the user wants to create a new module or workflow' and provides a pipeline for subsequent steps. Lacks explicit 'when not to use' or direct alternatives, but the context is sufficient for decision-making.

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 and destructiveHint=false. The description adds value by specifying that a pre-signed S3 URL with 1hr TTL is returned, which is useful behavioral context 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?

The description is two sentences with no wasted words. The main purpose is front-loaded, and each sentence adds essential 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 simple read-only file download tool returning a URL, the description is complete. It covers operation, input hints, and output format. No output schema is needed, and the tool is well-documented for its complexity.

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 baseline is 3. The description adds context about how 'guid' and 'fileName' construct the URL path, but does not significantly enhance the parameter meanings beyond the schema descriptions.

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 clearly states the tool's purpose: 'Download a file by module name' and explains that it returns a pre-signed S3 URL. It distinguishes from sibling tools like upload_file by focusing on download and URL generation.

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 description provides implicit usage context (construct URL from field.path) but does not explicitly state when to use this tool versus siblings like upload_file or confirm_upload. No direct alternatives or exclusions are mentioned.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: it changes nothing, performs no activity, and returns specific current data plus activity names, though it omits error or not-found 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?

Two sentences, front-loaded with the core purpose, then the return behavior and activity-execution routing. Every sentence adds distinct value without redundancy.

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 appropriately explains what the tool returns: current field values, state, audit metadata, and available activity names. Combined with annotation-covered safety and fully documented schema parameters, an agent has enough context to call it 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%, so the schema already documents module, entryId, and workspaceId. The description only reinforces lookup-by-ID and does not add syntax, format, or workspace-mode details 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?

The description gives a specific verb and resource: 'Read-only lookup of a single entry by its ID.' It also distinguishes the scope from list_entries by specifying a single entry, and from get_entry_history by focusing on current field values, state, and available activities.

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 clearly routes the agent for follow-up activity execution: 'to perform one, use get_form then submit_activity.' However, it does not explicitly contrast this tool with get_entry_history or state when current-state lookup is preferable over history retrieval.

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 non-destructive read-only behavior. Description adds value by specifying output format (chronological list with field-level changes and AI traceability), going beyond 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?

Two concise sentences, front-loaded with verb and resource, no fluff. Every sentence adds value.

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?

Describes purpose and return content well. However, missing mention of pagination (page parameter) and required parameters (module, entryId). Schema covers them, but description could be more complete.

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 covers all 4 parameters with descriptions (100% coverage). Description does not add further parameter details, but baseline 3 is appropriate since schema does the work.

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?

Clearly states it gets audit trail and comments for an entry, mentioning specific return content (chronological actions, field-level changes, AI traceability). Distinguishes from siblings like get_entry, which returns the current entry, not history.

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?

Implicitly suggests use when audit trail needed, but lacks explicit when-not or alternative tools. Among siblings, get_entry is for current state, but no direct comparison.

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, but the description goes well beyond them: it discloses the response's actor semantics (who may perform the activity), ai_hint/ai_instruction, field label-vs-name mapping, and the no-fabrication policy with ai.confidence fallback. This is exactly the context an agent needs before driving submit_activity.

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 the purpose well, but the single dense block drifts into submission policy ('submit with a lower ai.confidence') and hint-handling rules that belong to submit_activity rather than to a read-only form lookup. Useful content, but not every sentence earns its place in this tool's description.

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: form fields, current values, options, actor, and ai_hint/ai_instruction are all named. Combined with the input schema, an agent has everything needed to call it and interpret the result.

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 is 3, but the description adds real meaning: it frames module+activity as a session-stable pair, explains that `activity` can be create/edit/view/custom, and clarifies how `input` keys relate to a field's `label` versus its name. It does not, however, add much for entryId or workspaceId.

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 ('Read-only lookup of the input form for one named activity of one module') and immediately differentiates from the sibling that performs the action ('it does not perform the activity (submit_activity does)'). An agent can distinguish this from submit_activity and get_entry 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?

Gives explicit when-to-use ('Call this before the FIRST submit_activity on each (module, activity) pair'), a reuse rule ('form schema is stable within a session'), and alternative sources for later values (get_entry/list_entries). It also routes behavior based on the returned actor value (ai/hybrid/human) and tells the agent what to do with user values that have no matching field.

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 indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: 'The output is round-trippable — modify and send back via update_module' and instructs to load inistate://schema before modifying. No contradictions with 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?

The description is concise with two sentences covering purpose and workflow, plus a resource instruction. Every sentence adds value with no wasted words.

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 no output schema, the description adequately conveys that the output is the full module definition and round-trippable. It covers how to use it in a workflow and prerequisites. Could mention return format but not essential for a getter.

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% with clear descriptions for both parameters. The description does not add additional meaning beyond the schema, so baseline score of 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 description clearly states it retrieves the full module definition with stable IDs, using the verb 'get' and specifying 'full module definition'. It distinguishes from siblings like list_modules (which lists) and get_module_schema (likely different scope) by emphasizing round-trippability and the modify workflow.

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 description explicitly advises using this tool when modifying a module to preserve IDs and provides a modify workflow. It gives clear context but does not explicitly state when not to use it, though the workflow implies a sequence.

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, so the safety profile is covered; the description goes far beyond that by disclosing returned fields (stateDetails, activityDetails, ai_instruction), the actor semantics (ai/hybrid/human), partialFilter/profileOnly listing behavior, and how a listing's filter is auto-applied. This is substantial context an agent cannot get from 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?

Purpose is front-loaded in the first clause, and most content (tier guidance, actor semantics, listing behavior) earns its place. The listing paragraph is dense and packs multiple ideas into one sentence, but it stays on-topic for an agent that must call list_entries afterward.

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 carries the return-value burden and does so thoroughly, enumerating the fields each tier yields and their meaning. For a tool whose output drives downstream query construction, an agent has everything needed to call it 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%, so the baseline is 3, but the description adds genuine decision guidance for the tier enum (which tier to pick and why) rather than restating the schema's terse default. It adds nothing for workspaceId, which the schema already documents.

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: 'Read-only lookup of one module's schema', and immediately qualifies what it returns ('the canvas schema for a module'). The basic/extended tier split further pins down what the agent gets back, so it is distinguishable from generic module tools.

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 rules for the tier parameter ('Use basic for query operations. Use extended when you need to understand available activities and state transitions') and for listings ('pick the listing whose conditions already match the question and do NOT re-add them as filters'). It stops short of naming an alternative sibling such as get_module_canvas, leaving that boundary 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, yet the description adds substantial non-structured behavior: non-admin users cannot query the default 'Everything' view and must pass an accessible `listing` (access-denied names them), plus token-control behavior via `fields` and the exact system fields always vs conditionally returned.

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 the one-line purpose before three labeled context blocks (filtering, access, token control, state check), so structure is strong and each paragraph earns its place. It is on the long side, but the density is justified by the 11-parameter, nested-filter surface.

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 carries the return-shape burden and does so by explaining `data` pruning and always-present entryId/documentId/state fields. It remains silent on pagination metadata and several simple parameters (sortBy, currentPage), so a small completeness gap persists.

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 55%, and the description compensates heavily for the hard parts: filter key = field display name, operator-object grammar (contains/startsWith/min/max/between/after/before/empty/exists/is/not/excludes), {or:[…]} and implicit AND, and 'me'. However, sortBy, state, and currentPage still receive no meaning anywhere, leaving gaps.

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?

Opens with a specific verb+resource plus scope: 'Query entries with filters, sorting, pagination.' An agent can distinguish this list-level retrieval from get_entry (single) and aggregate_entries, but the description never names those siblings explicitly, so differentiation is inferred from scope rather than stated.

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?

Provides rich operational context: filter operator grammar, OR/AND composition, 'me' self-match, and the rule to check `state` before totalling/ranking. It lacks explicit when-to-use-this-vs-alternatives routing (e.g., point counting tasks at aggregate_entries), so it is clear context without exclusion guidance.

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. Description adds context: modules are 'discoverable', and behavior depends on workspace state (stateless vs stateful via set_workspace). No contradiction, and supplements annotations with usage-specific 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?

Two sentences: first states purpose, second provides usage guidance. Front-loaded and efficient with no extraneous 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?

Given 1 optional parameter, high schema coverage, no output schema, and clear annotations, the description fully covers what an agent needs: purpose, when to use, and parameter semantics. No 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 covers workspaceId with description. Description adds conditional semantics: 'Omit if set via env or set_workspace; required in stateless/remote mode', which clarifies when the parameter is needed beyond schema constraints.

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?

Description clearly states 'List all discoverable modules in the current workspace', specifying verb (list) and resource (modules). It distinguishes from sibling set_workspace by noting that set_workspace already returns this list, avoiding redundancy.

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: 'call this only to refresh it or when operating stateless without set_workspace'. Provides clear context and alternative, guiding appropriate invocation.

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, but the description adds behavior those annotations cannot express: automatic workspace selection when a single match occurs, the fact that a module list is returned in that case, and that admin listing is scoped to own memberships unless `search` is passed. This is genuine disclosure beyond structured fields.

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 front-loaded sentences, each carrying distinct information (purpose, call order/auto-selection, admin search behavior). No filler or repetition of the title.

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, yet the description explains the meaningful return case (module list returned on single match) and the routing decision that follows. For a zero-required-parameter read tool, nothing an agent needs 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?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: `search` changes admin behavior from listing own memberships to finding any workspace by name. It clarifies semantics of the optional filter well beyond the schema's 'case-insensitive name filter'.

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 workspaces the current user has access to') and bounds the scope to accessible workspaces. This is easily distinguishable from siblings like list_modules or set_workspace.

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 says it is 'typically the first call of a session' and names the branch condition: if exactly one workspace matches, no set_workspace or list_modules is needed; otherwise call set_workspace next. It also distinguishes admin behavior of `search`. Alternatives and exclusions are given, 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 only declare readOnly/destructive/idempotent/openWorld flags; the description adds critical behavior beyond them — the URL expires in ~1 hour, the PUT requires Content-Type to exactly match contentType or S3 returns 403, and the returned s3Key must be passed to confirm_upload. This is rich operational context not present in structured fields.

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 the key routing decision (default vs fallback) and then enumerates the flow compactly. It is dense and slightly crammed with clauses, but every sentence contributes necessary operational 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 multi-step upload tool with no output schema, the description supplies the complete flow, expiry caveat, error condition, and how to use the result (s3Key path for submit_activity). An agent has everything needed to execute the full sequence without further documentation.

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 each parameter (module, fileName, fileSize, contentType, workspaceId) is already documented in the schema. The description reiterates the 500MB limit and contentType matching but adds no syntactic or semantic detail beyond what the schema provides; 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 action (request an upload URL) and explicitly establishes it as the DEFAULT upload path, distinguishing it from the fallback sibling upload_file. The multi-step flow makes the tool's role unambiguous.

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 says when to use this tool ('DEFAULT upload path for every file up to 500MB') and when to use the alternative ('upload_file is only the fallback if this flow fails'). It also gives the exact sequence of follow-up calls (confirm_upload, submit_activity), leaving no routing ambiguity.

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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds real context beyond that: the mutation is session-scoped, the response carries the module list, and the stateless-mode caveat changes behavior. It stops short of describing persistence or what happens on an invalid name/ID.

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 two sentences are tight and front-loaded with the key constraint. However, the trailing block of four workflow sequences (design/execute/modify/query) concerns other tools' chaining rather than setting a workspace, and reads as bulk that could live in each tool's own description.

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 stating that the response includes the workspace's module list, which is the main thing an agent needs to know. The one-parameter, non-destructive, idempotent mutation is adequately characterized; only error/invalid-input behavior is unaddressed.

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 parameter is fully documented in-schema (accepts ID or exact name from list_workspaces). The description only echoes the workspaceId name in the stateless-mode note and adds no new format or validation semantics, 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 and resource ('Set the active workspace for the current session') and immediately distinguishes itself from siblings by noting that list_workspaces is the discovery tool and list_modules is only needed to refresh. An agent can tell exactly what this does versus switch_mode or list_workspaces 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 explicit routing: use this in stateful sessions, but 'in stateless/remote mode, prefer passing workspaceId directly to each tool instead' — a genuine when-not-to-use rule naming the alternative. It also clarifies when list_modules is actually required, removing a common false-positive call.

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 destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the write/non-idempotent profile is covered structurally. The description nonetheless adds substantial context beyond them: fail-soft sequential execution, per-item outcomes returned in `results`, per-item `ai` wholly replacing (not merging with) the top-level default, and the actor/changeStatus/state-override rules that force `confirmed: true`. This is real disclosure that goes well past what the annotations state.

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 and the routing decision before moving to mechanics and guardrails. It is dense — the "Max 100 items" point duplicates the schema's maxItems constraint — but nearly every sentence carries actionable 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 compensates by naming what returns in `results` (success, entryId, flagged, validation details) and how to correlate via `clientRef`. Combined with batch-level guardrails and chunking guidance, an agent has everything needed to invoke this correctly at scale.

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 67%, and the description fills key gaps: it clarifies the no-partial-merge semantics of per-item `ai`, the correlation purpose of `clientRef`, and the precise trigger conditions for `confirmed` (actor='hybrid', activity='changeStatus', or any state override). It does not restate the simpler item fields already documented in the schema, which is 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 ("bulk variant of submit_activity: one call applies one named activity of one module to many entries") and explicitly contrasts itself with the sibling submit_activity. An agent can distinguish it from submit_activity and the read-only siblings 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?

Names the alternative and the condition that selects it: "Use instead of N sequential submit_activity calls when creating/editing many rows — one tool turn instead of N." It also supplies operational guidance (max 100 items, chunk beyond that) and the guardrail conditions that gate use of `confirmed`.

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 past the annotations (destructive, non-idempotent, closed-world): it discloses confidence-threshold gating that suppresses the transition and flags the entry, server-side guard rules (human/hybrid actor, state-change confirm, confidence-inflation), and points to inistate://guardrails. That is exactly the mutation-risk context an agent needs before calling.

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 the core write semantics and the activity/ai requirements before the guardrail caveats. It is dense and clause-heavy, but nearly every clause (form-first, threshold suppression, guard rules, schema pointer) carries operational weight.

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 12-parameter, nested-object mutation tool with no output schema, it covers prerequisites, gating behavior, and where the input shapes live (inistate://schema/runtime). It does not describe what a successful submission returns, though the absent output schema limits how much that matters.

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 already 83%, so the baseline is 3; the description adds real meaning by explaining that `activity` holds data-driven standard or custom activity names (not hidden tools), that `ai` is mandatory with reasoning+model+confidence, and what happens when confidence falls below the activity's threshold.

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?

Opens with a specific verb+resource+scope: 'one call performs exactly one named activity on one entry of one module, and nothing else runs.' That scope statement implicitly separates it from the bulk sibling submit_activities and from read tools like get_entry, so an agent can route 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 concrete prerequisites: call get_form before the first submission per (module, activity) and reuse its schema, and use get_module_schema tier=extended to discover custom activity names. It stops short of naming submit_activities as the multi-entry alternative even though the schema exposes entryIds 'For bulk ops'.

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 mark the tool as idempotent and non-destructive. The description adds crucial behavioral context: it reveals that the tool/resource list refreshes via 'list_changed' after the call and clarifies what tools/resources are available in each mode. No contradictions with 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?

The description is a single paragraph with no wasted sentences, but it is slightly verbose. It front-loads the core action and then lists modes and their contents efficiently. Minor room for tightening, but overall strong.

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 the simple single-parameter schema, no output schema, and informative annotations, the description fully covers the tool's behavior: what it does, the effect of each mode, and a side effect (list refresh). It leaves no obvious 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% and the description expands on each enum value beyond the schema's single-word labels. For example, it explains that 'configure' includes entry CRUD and design tools, while 'frontend' adds the inistate://frontend-guide resource. This adds meaningful clarity.

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 uses the specific verb phrase 'Switch tool surface' and lists the three modes (configure, runtime, frontend) with their distinct feature sets. This clearly differentiates it from sibling tools, which are all separate resource or action tools.

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 description explains what each mode enables and explicitly advises using 'frontend' when the user wants a custom UI. It does not explicitly state when not to use the tool, but the mode descriptions provide enough context to select appropriately.

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 destructiveHint=true and idempotentHint=true, and the description goes beyond them by explaining exactly what is destroyed: a passed section replaces the entire list, so any existing item omitted is lost. It also discloses the id-matching rule (rename vs. add) and the pre-flight requirements, which the annotations alone cannot convey.

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 destructive replacement rule, then prerequisites and validation. Dense and all four sentences carry information, though the parenthetical detail about id/rename/omit makes it slightly heavy for a first read.

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 10-parameter, deeply nested mutation tool this covers the critical workflow: how sections behave, what to call first, and how to validate. With no output schema, the response shape is only partially covered (it references cardStatus but not the rest of the return payload), leaving a small gap.

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 already 90%, so the baseline is 3; the description still adds real meaning by explaining the id-matching/renaming and omit-id-to-add semantics across sections, plus the section-replacement rule that no single property description states. It stops short of describing id/workspaceId sourcing beyond pointing at get_module_canvas.

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?

Opens with a specific verb+resource ('Update an existing module') and immediately scopes which parts can change (information/states/activities/flows). It also distinguishes itself from create_module by noting internal validation parity, so an agent can place it relative to siblings 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 explicit prerequisites and alternatives: 'Always call get_module_canvas first to obtain the stable module id and item ids,' and for partial payloads 'validate the merged canvas with validate_design first.' It also states what happens to omitted sections, so the when-to-use and how-to-sequence guidance is complete.

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 cover the mutation profile (readOnly=false, idempotent=false, destructive=false), and the description goes well beyond them: it discloses the return shape ({path, filename, mimeType, size}), instructs how to consume it (path as the File/Image value in submit_activity), and states two hard constraints — 50MB max and a blocked-extension list. This is exactly the kind of operational context annotations cannot carry.

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?

A single dense paragraph with the fallback constraint front-loaded in caps, followed by mechanism, return shape, and limits. Every clause carries actionable information; nothing is redundant 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?

Despite no output schema, the description documents the return object and its downstream use, and covers size/extension limits and the routing alternative. For a 5-parameter mutation tool, an agent has everything needed to call it correctly and interpret the result.

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 all five parameters are already documented in the schema, making 3 the baseline. The description only restates the base64 encoding already noted in the schema and does not clarify module scoping, workspaceId requirements, or mimeType defaults beyond what the schema says.

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 (uploads a file via base64) and immediately frames its role as a fallback, distinguishing it from the request_upload_url/confirm_upload sibling flow. An agent can identify both what it does and where it sits in the upload pipeline 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?

Explicitly names the preferred alternative (request_upload_url + confirm_upload) and the precise condition that selects this tool: 'call this only after that presigned flow has actually failed.' This is a textbook when-to-use/when-not-to-use statement with the alternative named.

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 indicate read-only and idempotent behavior. The description adds that it runs the same checks as create_module/update_module and is a non-submitting validation, reinforcing safety. However, it could mention the return value (e.g., validation errors) for full transparency.

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?

Two sentences: first states core purpose, second provides usage guidance. No wasted words, front-loaded, and easy to scan.

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 simple validation tool with good annotations and schema, the description covers the essential purpose and usage context. It could mention the output (e.g., success/error response) but overall is sufficiently complete.

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 description adds limited value beyond schema. It does provide extra guidance on workspaceId (omit if set via env or set_workspace) and reiterates mode semantics, which is helpful but not extensive.

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 clearly states the tool validates a module schema without submitting, and distinguishes it from create_module and update_module by positioning it as a dry-run for iteration. The verb 'validate' and resource 'module schema' are specific and distinct from sibling tools.

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 description explicitly explains when to use this tool (iterating on a draft, before partial update_module) and when it is optional (create_module already runs these checks). It provides clear alternatives and context.

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