Create, build and deploy projects, roll back with checkpoints, connect custom domains, and search…
Scored across 54 tools
Most tools have distinct resource/action targets, and descriptions explicitly differentiate near overlaps such as search_workspace vs search_project_code and the two notification-marking tools. Some ambiguity remains around usage/plan tools (get_usage, upgrade, get_subscription) and model-backed answer tools (create_chat_completion, web_search), but overall an agent can reasonably select the right tool.
Nearly all tools use snake_case with a predictable verb_noun pattern (create_project, get_project_files, deploy_project, revoke_api_key). A few names deviate, notably upgrade and web_search, and create_chat_completion is slightly verbose, but the overall convention is stable and readable.
At 54 tools, the surface is far beyond the typical 3–15 range and is likely overwhelming for an agent to navigate reliably. Although the underlying platform is broad and many tools are meaningful, this is an extreme tool-count mismatch for a single MCP server.
Core project lifecycle, files, checkpoints, deployment, domains, backend provisioning, code indexing, API keys, billing, notifications, connectors, and search are all well covered. Minor gaps exist around collaboration/member management and some secondary operations like deployment history or API-key updates, but agents can work around them.
Archive (archived=true) or un-archive (archived=false) a project. Archiving hides it from the active list without deleting anything; it is fully reversible.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) | |
| archived | Yes | true to archive, false to bring it back |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations by explaining the actual state effect (hidden from active list, data retained, fully reversible), which is meaningful for a mutation tool. It does not address permissions or the response shape, but the destructiveHint=false and idempotentHint=true annotations already carry the safety profile.
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 compact sentences, front-loaded with the action and its two modes, with the reversibility note immediately after. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, non-destructive flag toggle with full schema coverage and complete annotations, the description supplies everything an agent needs to call it correctly; no output schema means return values need not be described.
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 parameters are already documented in the schema. The description restates the archived true/false meaning but adds no format or edge-case detail beyond that, 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 ('Archive ... a project') and covers both directions via the archived flag. The 'hides it from the active list without deleting anything' clause implicitly separates it from delete_project and restore_project in the sibling list.
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 context for when to use it: hiding a project without destroying data, which steers the agent away from delete_project. It stops short of naming the alternative tools explicitly, so it is clear but not fully routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel the build currently running on a project. Work the build had not yet saved is discarded.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=true. The description adds meaningful context beyond that: that unsaved work is discarded, telling the agent the real cost of the call. It stops short of describing error behavior or what happens with no active build.
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 short sentences, front-loaded with the action and followed by the consequence. Nothing is redundant and every sentence earns 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?
For a one-parameter mutation whose safety profile is fully covered by annotations, the description supplies the key missing piece (data loss on cancel). It could go further on failure/no-op cases but is otherwise sufficient to call 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 coverage is 100% and the sole parameter is already documented as a 'Project UUID'. The description only implies that the id refers to the project, adding no format or constraint details beyond the schema, so baseline 3 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 ('cancel the build') plus scope ('currently running on a project'), so an agent can tell it apart from read-only siblings like get_build_status or list_builds. It does not explicitly name an alternative, so it stops short of a 5.
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 'currently running' qualifier implies when the tool applies, but there is no explicit when-not guidance (for example what to do if no build is running) and no named alternatives. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a subdomain label is free for this project and, if not, get suggestions. The project's own current subdomain reads as available.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) | |
| subdomain | Yes | Label to check, e.g. 'my-app' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world. The description adds non-obvious behavior beyond that: it returns suggestions when the label is unavailable, and the current subdomain is reported as available. Return shape and rate limits are not covered, but this is meaningful added context.
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, zero waste, with the core operation front-loaded and the availability caveat following. Every clause earns 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?
For a simple two-parameter read-only check with no output schema, the description covers what it does, the suggestion fallback, and one important edge case. It could say a bit more about what the response contains, but nothing needed to call 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% and both parameters (project UUID, subdomain label) are already documented in the schema. The description reinforces the 'this project' scoping but adds no syntax or format detail beyond what the schema provides, so the baseline 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?
States a specific verb ('check') and resource ('subdomain label') with scope ('for this project') and secondary behavior ('get suggestions'). It is clearly distinguishable from siblings like update_project_subdomain or lookup_domain, though it never names 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: check availability before setting a subdomain. The note that the project's own subdomain reads as available is a helpful usage caveat, but there are no explicit when/when-not rules or named alternatives (e.g. lookup_domain vs update_project_subdomain).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete every embedding for a project. Code search returns nothing until the project is indexed again. Project files are not touched.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description's job is to add consequence detail — and it does: search silently returns nothing until re-indexing, and project files survive. That is exactly the post-destruction state an agent needs. It stops short of noting permissions, whether the project must be indexed at all, or whether removal is async.
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 short sentences, front-loaded with the action, then the consequence, then the safety boundary. Every sentence adds distinct information with no repetition of the name, title, or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive mutation with no output schema, the description covers what is destroyed, the observable aftereffect, and what is preserved — enough to call it correctly. Minor gaps remain around preconditions (must the project exist / be indexed) and whether the operation blocks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single documented 'project_id' (UUID), so the schema already carries the parameter semantics. The description adds no format, scope, or validation detail beyond it — 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: 'Delete every embedding for a project.' It also scopes what is NOT affected ('Project files are not touched'), which distinguishes it from destructive siblings like delete_project. It never names the inverse tool (index_project_code), so it falls just short of explicit sibling differentiation.
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?
'Code search returns nothing until the project is indexed again' implies the intended workflow (use before re-indexing), but usage is only inferred, not stated. No explicit when-to-use, when-not-to-use, or named alternative such as index_project_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new API key. The raw key is returned ONCE — hand it to the user and never repeat or store it. Every MisarDev key has full API access; keys expire (default 90 days, max 365).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Key label (1–80 chars) | |
| ip_allowlist | No | Optional IPs/CIDRs allowed to use the key | |
| expires_in_days | No | Days until expiry (1–365, default 90) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a non-read-only, non-idempotent, non-destructive mutation, and the description adds genuinely new behavioral facts: the raw key is returned exactly once, must be delivered and not stored, all keys carry full API access, and expiry defaults to 90 days with a 365-day ceiling. These are the details an agent needs to avoid silently losing the secret or mis-assuming scoped permissions.
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 short sentences, front-loaded with the action, then the irreversible one-time-secret warning, then expiry facts. No filler and nothing that could be dropped without losing 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 carries the return-value burden and does so: the created key is returned once and never again. Combined with the expiry rules and full-access statement, an agent has everything needed to call this correctly and handle the result safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds a semantic constraint the schema doesn't state: every key has full API access, which reframes ip_allowlist as a network restriction rather than a permission scope. The expiry default and max in the description duplicate the schema, but the full-access note is real added value.
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 API key') so the agent can distinguish it from list_api_keys, revoke_api_key, and other siblings. It doesn't name those siblings explicitly, so differentiation relies on the trivially obvious verb, not on stated routing.
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 conveys usage context ('hand it to the user and never repeat or store it'), which implies this is the provisioning step in a key lifecycle. However, it never says when to use this versus list_api_keys or revoke_api_key, and gives no prerequisites about who may create keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a one-shot, non-streaming chat completion on MisarDev's OpenAI-compatible model API. model='misar-online' grounds the answer in the web with citations; omit model for the default coding model. Spends model credits.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Model id; 'misar-online' or 'misar-search' for web-grounded answers | |
| messages | Yes | OpenAI-style messages: [{ role: 'system'|'user'|'assistant', content: string }] | |
| max_tokens | No | Maximum tokens to generate | |
| temperature | No | Sampling temperature |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real information beyond the annotations: the call is one-shot and non-streaming, and it 'Spends model credits' — a cost signal the readOnlyHint annotation does not convey. It does not mention authorization requirements or rate limits, but against annotations that already state openWorldHint and non-idempotency this is solid.
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 short sentences, front-loaded with the operation and mode, followed by model routing and cost. Nothing is redundant and every sentence carries a decision-relevant fact.
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?
Covers mode, model routing, and cost for a 4-parameter tool with no output schema. The remaining gap is the response shape — the agent is told citations appear but not how the completion and citations are returned — which is minor but not fully covered.
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; the description earns above that by explaining the effect of omitting model (default coding model) and that 'misar-online' yields web grounding with citations. It still says nothing about temperature or max_tokens behavior, which the schema only names.
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 ('Run a one-shot, non-streaming chat completion') against a named provider API, and the non-streaming qualifier tells the agent the execution mode. It does not differentiate itself from the sibling web_search tool, which overlaps in purpose, so it stops short of a 5.
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 model-selection guidance ('misar-online' for web-grounded answers, omit for the default coding model), which is useful invocation context. However it never says when to prefer this tool over the sibling web_search, nor when streaming or task-specific alternatives should be used; usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new, empty project (optionally seeded with a file map). Counts against the plan's project quota. To start from a starter instead, use use_template.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Project name (max 100 chars) | |
| files | No | Initial file map: keys are relative file paths, values are file contents | |
| settings | No | Project settings (e.g. framework, styling) | |
| description | No | Optional project description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=false. The description adds non-obvious behavioral context beyond that: the call consumes the plan's project quota, which an agent could not infer from the schema or 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 short sentences, each carrying distinct information: what it creates, a cost side-effect, and a routing alternative. The core action is front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter creation tool with full schema coverage and covered safety annotations, the definition covers purpose, cost, and alternatives. The one omission is what is returned (e.g., the new project's identifier), which matters since there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents name, files, settings, and description thoroughly. The description's phrase "optionally seeded with a file map" only lightly reinforces the files parameter and adds no format detail 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?
States a specific verb and resource ("Create a new, empty project") and immediately qualifies the scope with the optional file-map seeding. It is clearly distinguishable from siblings like use_template, duplicate_project, and import_artifact because it emphasizes starting empty.
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 alternative path ("To start from a starter instead, use use_template"), which is the most likely confusion point. It does not address other plausible alternatives such as duplicate_project or import_artifact, so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one checkpoint from a project's version history. It can no longer be restored afterwards, and the last remaining checkpoint cannot be deleted. Confirm with the user first.
| Name | Required | Description | Default |
|---|---|---|---|
| checkpoint_id | Yes | Checkpoint ID (from list_checkpoints) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations (which only flag destructiveHint/idempotentHint) by explaining irreversibility ('can no longer be restored afterwards'), the last-checkpoint guard, and a confirmation requirement. These are exactly the behavioral traits an agent needs before invoking a destructive mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action and risk before the guard and confirmation. No wasted words and 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 destructive single-param tool with no output schema, the description covers irreversibility, the deletion guard, and the confirmation protocol. Slightly richer context on what happens to dependent state (e.g., deployments referencing the checkpoint) would make it 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?
Only one parameter, and the schema already documents it at 100% coverage including the source ('from list_checkpoints'). The description adds no parameter 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?
States a specific verb and resource ('Delete one checkpoint') and scopes it to a project's version history, so it is distinguishable from restore_checkpoint and rename_checkpoint. It does not explicitly name those siblings, which keeps it just short of a 5.
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 a concrete precondition ('Confirm with the user first') and states the blocking edge case ('last remaining checkpoint cannot be deleted'). It lacks an explicit pointer to alternatives like archive_project or how to recover, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a project to the trash. It disappears from every list and route immediately; restore_project brings it back during the retention window. Confirm with the user first — anything published from it stops being editable.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real beyond-schema context: the item vanishes from all lists and routes immediately, is recoverable only within a retention window, and published output stops being editable. It omits how long the retention window is, but the behavioral picture is otherwise strong.
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 short sentences: what it does, its immediate effect and recovery path, then the caution. Front-loaded, 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?
For a destructive single-parameter tool, the definition covers effect, reversibility, and the confirmation requirement, and annotations carry the safety hints. The main omission is the retention window duration, which affects how urgent restore is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, and schema coverage is 100% — the schema already documents 'id' as a project UUID sourced from list_projects. The description adds no format or sourcing detail beyond that, 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 ('Move a project to the trash') and immediately distinguishes the operation from restore_project, which reverses it. An agent can tell this apart from siblings like archive_project or unpublish_project 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 a clear precondition ('Confirm with the user first') and names the recovery path ('restore_project brings it back during the retention window'). It does not explicitly contrast with archive_project, so the boundary between trashing and archiving is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a project to the public internet on the MisarDev runtime (optionally at a chosen subdomain). The site becomes reachable by anyone. Confirm with the user before calling, check the address first with check_subdomain, and follow with get_deployment_status. Counts against the plan's deploy quota.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) | |
| subdomain | No | Subdomain label to publish at (e.g. 'my-app'); omit to keep the current one | |
| public_gallery | No | List the published app in the public showcase (omit to leave unchanged) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructive=true and openWorldHint=true, but the description adds real context: the site becomes reachable by anyone (public exposure), it counts against the deploy quota, and there is a required confirmation step plus a recommended follow-up tool. That is meaningful behavior beyond the structured hints.
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 short sentences, front-loaded with the core action and effect, then prerequisites and cost. No filler or 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?
For a mutation tool without an output schema, the description covers the exposure impact, quota cost, confirmation requirement, prerequisite check, and follow-up verification tool. An agent has enough to call it correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters including subdomain and public_gallery are already documented in the schema. The description only restates the optional-subdomain aspect without adding format or edge-case meaning, 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?
States a specific verb and resource ('Publish a project to the public internet on the MisarDev runtime') plus the optional subdomain scope. This is distinguishable from siblings like update_project_subdomain and unpublish_project, since the effect (public reachability) is explicit.
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 preconditions: confirm with the user before calling, check the address first with check_subdomain, and follow with get_deployment_status. It also names the quota cost, which affects whether to call at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy a project (files and settings) into a new project you own, named after the original. Counts against the plan's project quota. Any member with read access may duplicate.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world. The description adds genuinely new context: it consumes the plan's project quota and requires only read access on the source. It stops short of describing naming collisions with an existing project or whether the copy is immediate.
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 short sentences, each carrying distinct information: what is copied, the quota cost, and the permission rule. The action is front-loaded with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and solid annotation coverage, the description gives the essentials an agent needs — scope of the copy, quota impact, and authorization. Only edge-case behavior (duplicate naming, async completion) is left unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'id' parameter is documented as a project UUID sourced from list_projects. The description adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Copy') and resource ('a project (files and settings)'), and clarifies the output is a new project owned by the caller named after the original. This clearly separates it from create_project (blank/new) or use_template (template-based), which are the nearest 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?
Implies usage via 'Any member with read access may duplicate,' which gives an eligibility condition, but never states when to prefer duplicate_project over create_project or use_template, nor any exclusions. The reader must infer the alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get whether a project currently has a build running and its latest build state. Poll this rather than assuming a build finished.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds one useful behavioral note — that state is volatile and should be re-polled rather than assumed — but says nothing about what the states look like or whether a build may appear between polls.
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 short sentences: the first states what is returned, the second states the operational habit. Nothing is padded and the core purpose 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?
For a simple single-parameter read with no output schema, the description tells the agent both what comes back conceptually (running flag plus latest state) and how to use it. The only gap is enumerating possible build states, which is minor.
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?
There is a single parameter with 100% schema description coverage ("Project UUID"), which the schema fully documents. The description adds no further meaning about the identifier, 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?
States a specific verb and resource: reads a project's current build-running flag plus latest build state. It is clear on its own, but it doesn't distinguish itself from nearby siblings such as list_builds or get_deployment_status, which an agent could easily mistake for the same question.
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?
"Poll this rather than assuming a build finished" gives a genuine usage cue about repeated invocation after triggering a build. However, no alternatives or exclusions are named, so the agent gets no guidance on when list_builds or get_deployment_status would be the better call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get embedding statistics for a project — how many files and chunks are indexed and when.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project UUID |
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 useful behavioral context by stating what the statistics include — file/chunk counts and indexing timestamps — but does not describe permissions, rate limits, or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a single, front-loaded sentence with no wasted words. The resource and scope appear immediately, followed by the specific statistics returned.
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, single-parameter statistics tool with full schema coverage and safety annotations, the description is nearly complete. It explains what the stats represent, though it does not mention whether results are scoped to the latest build or include historical indexing events — a minor gap for an agent interpreting the output.
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?
There is only one parameter, project_id, and the schema already documents it at 100% coverage as a project UUID. The description does not add any syntax, format, or selection guidance beyond what the schema provides, so the baseline score of 3 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?
The description states a specific verb and resource — getting embedding statistics for a project — and clarifies exactly which statistics are returned: file count, chunk count, and indexing timestamps. It is clear enough to distinguish this from index_project_code or clear_code_index, but it does not explicitly name those siblings or state the contrast.
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 only implied: an agent can infer this tool is for inspecting index status, likely before or after indexing or searching. However, the description gives no explicit when-to-use guidance, prerequisites, or comparison with alternatives such as index_project_code, clear_code_index, or search_project_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a project's custom domain, its status, the DNS record the user must set, and whether DNS already resolves to the platform (TLS is issued automatically once it does).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond them: the tool reports the required DNS record, whether DNS resolves, and that TLS is issued automatically once it does. The one gap is the not-configured case — it doesn't say what comes back when no custom domain exists.
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 front-loaded sentence where each clause contributes return-value information; the parenthetical about TLS earns its place as scope clarification. Slightly dense, but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining the return payload and does so concretely (status, DNS record, resolution flag, TLS). Only the empty/not-set state and error behavior are left unspoken.
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% for the single 'id' property, and the description's phrasing 'a project's custom domain' reinforces that the identifier is a project UUID. Minimal added syntax, but no ambiguity remains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Get a project's custom domain') and immediately enumerates the returned facets (status, DNS record, resolution state), which distinguishes it from mutation siblings set_custom_domain and remove_custom_domain. It does not explicitly position itself against lookup_domain or check_subdomain, which look closely related.
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 only implied by the read verb; there is no explicit statement of when to call this versus lookup_domain, check_subdomain, or set_custom_domain. An agent can infer it is the read path, but nothing confirms the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a project's current deployment: whether it is live, its URL, subdomain and custom-domain state. Call after deploy_project to confirm the site is actually up before telling anyone it is.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds useful behavior of its own: the tool reports live status, URL and domain state, and the usage note makes clear the result is meant as an authoritative liveness check. It doesn't cover failure modes or the shape of the response.
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, both front-loaded: the first defines scope and outputs, the second defines when to call it. No wasted clauses.
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 carries the return-value burden, and it does so at a high level by naming live state, URL, subdomain and custom-domain state. It is nearly complete for a one-parameter read tool, though it leaves the possible status values and failure behavior unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With one parameter at 100% schema description coverage, the schema already explains that 'id' is a project UUID from list_projects. The description contributes no additional parameter meaning, so the baseline 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 states a specific verb and resource ('Get a project's current deployment') and enumerates what is returned: live state, URL, subdomain and custom-domain state. That content also distinguishes it from siblings like get_build_status and get_custom_domain, which cover different concerns.
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 names an explicit trigger and ordering: 'Call after deploy_project to confirm the site is actually up before telling anyone it is.' This gives the agent a clear when-to-use condition and names the sibling that precedes it, though it doesn't state exclusions such as when to prefer get_build_status mid-build.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one project by ID — name, description, settings, visibility, version and deployment fields. Read this before update_project so you change the current version, not a stale copy.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description still adds value by naming the returned field groups and disclosing the staleness/versioning risk that motivates the read-before-write pattern — context annotations cannot express.
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 short sentences, zero filler. The identification comes first and the workflow rationale second, so the load-bearing information 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?
With no output schema, the description compensates by listing the returned field groups (name, description, settings, visibility, version, deployment). Combined with the read-before-update rule, nothing an agent needs to call this 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 description coverage is 100% for the single 'id' parameter and already says it is a UUID from list_projects. The phrase 'by ID' in the description adds nothing beyond that; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get one project by ID') and immediately enumerates the fields returned, which separates it from list_projects (many) and update_project (mutating). An agent can distinguish it from every sibling 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?
Explicitly prescribes ordering: call this before update_project so you edit the current version rather than a stale copy. That is real when-to-use guidance, though it gives no exclusions (e.g. use list_projects when you only have a name).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show a full-stack project's database backend: whether one is provisioned, its schema name, table count and connection state.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds value by disclosing what the call actually reports (provisioning state, schema name, table count, connection state), which is meaningful 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?
One front-loaded sentence that names the resource first and then enumerates the returned fields. No filler, no 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 reasonably compensates by listing the returned data points. For a simple single-parameter read tool, that is close to sufficient; only edge-case behavior (e.g., what is returned when no backend exists) is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single parameter with 100% schema description coverage ('Project UUID'), so the schema already carries the semantics. The description never references the id or clarifies that an unprovisioned project is still a valid input; 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 ('Show') plus a clearly scoped resource (a full-stack project's database backend) and it enumerates the four data points returned. It is distinguishable from get_project by focusing on backend state, though it never names that sibling explicitly.
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 only implied: the read-only framing suggests checking backend status rather than creating one, and provision_project_backend exists as the obvious counterpart. There is no explicit 'use this when... / use X instead when...' guidance or statement of prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a project's file tree with file contents. Use this to read code before answering questions about it or proposing an update_project change.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds that the result includes file contents, but it does not mention size limits, truncation behavior, or binary/large-file handling, which matter for a tree-with-contents read.
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 action and followed by the intended use case. There is no wasted wording.
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 getter with annotations covering safety, the description is largely complete: it says what is returned at a high level and when to use it. It could be stronger by clarifying that the full tree with contents may be large or by mentioning practical limits, but no critical information 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% for the single id parameter, including that it is a Project UUID from list_projects. The description adds no parameter-specific detail beyond what the schema already provides, so baseline 3 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?
The description states a specific verb and resource: get a project's file tree with file contents. This clearly distinguishes it from sibling tools like search_project_code and write_project_files, and the purpose is understandable 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?
It gives clear usage context: read code before answering questions or proposing an update_project change. However, it does not explicitly name alternatives such as search_project_code or state when not to use this tool, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a project's knowledge — the standing notes (product context, conventions, constraints) the AI builder reads on every change.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
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 clear. The description adds useful behavioral context by explaining that the returned content is standing notes the builder reads on every change, though it does not discuss permissions, empty-knowledge behavior, or return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single front-loaded sentence that leads with the verb and resource, then briefly clarifies the content of project knowledge. There is no redundant or filler text.
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 one-parameter read tool with annotations covering safety and no output schema, the description gives enough context to understand what is being retrieved. It could be slightly more complete by stating what the response looks like or what happens when no knowledge exists, but no critical call information 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?
There is one required parameter, and the schema has 100% description coverage, explicitly documenting it as a 'Project UUID'. The description adds no parameter-specific syntax or format detail beyond that, so the schema does the semantic work and the 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 uses a specific verb ('Read') with a specific resource ('a project's knowledge') and then defines what that knowledge contains: standing notes covering product context, conventions, and constraints. It is clearly distinguishable from the sibling update_project_knowledge, which mutates the same resource.
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 implies when this tool is useful by explaining that it returns notes the AI builder reads on every change, but it does not explicitly say when to use this versus get_project or update_project_knowledge. No exclusions or alternative-routing guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the account's subscription: plan, status, current period end and whether it cancels at period end.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 fully covered by structured fields. The description adds genuine value on the read side by naming the four data points returned, which compensates for the absence of an output schema. It stops short of describing field types, formats, or edge behavior for accounts without a subscription.
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 colon-led sentence that front-loads what is being fetched and then lists the returned fields. There is no filler and nothing redundant to cut.
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?
Because there is no output schema, the description must carry the return-value burden, and it does so for the key fields. It is slightly incomplete in that it does not state the value shapes (e.g. status enumerations, date format) or what is returned when no subscription exists, but for a simple read-only getter this is close to sufficient.
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 tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The gathered fields describe the response rather than any input semantics.
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 and enumerates exactly what the resource contains: plan, status, period end, cancellation flag. This clearly separates it from siblings like get_usage and list_plans, which cover metered consumption and available plans rather than the account's current subscription.
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 only implied: an agent can infer this is the tool for reading the current subscription, and the zero-parameter signature makes the scope unambiguous. However, there is no explicit when/when-not guidance and no routing to related siblings such as list_plans or upgrade, which an agent may need when the user asks about changing plans.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one template by ID — its description, stack and the files it would create.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template ID (from list_templates) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only, idempotent, non-destructive lookup. The description adds useful behavioral context by saying what the tool returns: the template description, stack, and files it would create. It does not mention error or permission behavior, but the annotation baseline is strong.
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 front-loaded sentence with no filler. It states the operation and the key return contents efficiently.
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 one-parameter read tool, the definition is complete enough: the schema documents the ID source, annotations cover the safety profile, and the description explains what the result contains even though there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter and schema description coverage is 100%, so the schema already documents that the ID comes from list_templates. The description adds no parameter-specific detail beyond 'by ID', which matches the baseline for high schema coverage.
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 states a specific verb and resource: get one template by ID. It also previews the returned content (description, stack, files). It is clear, but it does not explicitly distinguish this retrieval tool from siblings like use_template, so it falls short of a 5.
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 'by ID' phrasing implies this is a lookup tool, likely used after list_templates and before use_template, but the description never states when to use it versus those alternatives. Usage is therefore implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed usage for the account. format=quick returns a lightweight summary, format=dashboard the full dashboard data; analytics=true adds a per-day breakdown over days (default 30). For plan limits at a glance, use upgrade.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look-back window in days (default 30) | |
| format | No | Response format — omit for the default summary | |
| analytics | No | Include the detailed analytics breakdown (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the description only needs to add operational context — it does: the two response modes, the analytics augmentation, and the 30-day default window. It doesn't describe volume/size of dashboard output or any rate/latency characteristics.
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, zero filler, and the primary capability is front-loaded with alternatives in the second half. Every clause carries either scope, a mode, or a routing hint.
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, no-write-risk tool with a fully documented 3-parameter schema and no output schema, the description covers modes, defaults, and the alternative tool. What remains unspecified is the shape of the returned data (which metrics appear in 'quick' vs 'dashboard'), but the tool takes no required params and cannot mutate state, so this is a minor 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 100%, so baseline is 3, but the description earns a bump by explaining the interaction between parameters: analytics=true expands the breakdown *over the `days` window*, which the schema does not state. The per-parameter defaults are restated rather than added, but the linkage adds real 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?
States a specific verb and resource ('Get detailed usage for the account') and immediately explains the two format modes. It is distinguishable from most siblings, though the sibling set contains no other usage tool, so the name alone already disambiguates; 'usage' itself (quotas? analytics? billing?) is only clarified by the format values.
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 the agent away from this tool for a related need ('For plan limits at a glance, use upgrade'), and gives the conditions for choosing format=quick vs format=dashboard vs analytics=true. No explicit statement of when this tool is *not* useful beyond that single exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a published Misar artifact page into a project as imported/ARTIFACT_ID.html. The url must be exactly https://misar.ai/code/artifact/ARTIFACT_ID; anything else is refused before any fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID | |
| url | Yes | Artifact URL: https://misar.ai/code/artifact/ARTIFACT_ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare write (readOnlyHint=false), non-destructive, idempotent, and open-world behavior. The description adds real value beyond that: a validation gate that refuses bad URLs before any network fetch, and a deterministic output path that explains why the operation is idempotent. It does not explicitly say whether an existing imported/ARTIFACT_ID.html is overwritten, 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 sentences, no filler, with the core action and destination path front-loaded and the validation constraint immediately after. Every clause earns 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?
For a simple two-parameter tool with full schema coverage, annotations, and no output schema, the description covers the action, destination, and input validation adequately. The only missing piece an agent might want is what happens when the target file already exists, though idempotentHint implies overwrite-or-noop semantics.
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 parameters are already documented (id = Project UUID, url = artifact URL pattern). The description restates the URL pattern and adds the rejection behavior for malformed URLs, but adds nothing about the id parameter beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation.
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 (import), a specific resource (a published Misar artifact page), and the exact destination path (imported/ARTIFACT_ID.html). No sibling tool performs this operation, so the agent can distinguish it immediately from the surrounding project/file 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 establishes a hard precondition — the URL must match the exact misar.ai/code/artifact/ARTIFACT_ID pattern — which tells the agent when this tool will work and when it will be rejected before any fetch. It does not name alternatives or explicitly say when not to use it, but no sibling tool overlaps with this operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index a project's files for semantic code search (RAG). Pass the files to index as a path → content map; re-indexing a path replaces it. Metered — a paid-plan feature.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | File map to index: keys are file paths, values are file contents | |
| project_id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the write/idempotent/non-destructive profile, and the description adds real value beyond them: replace-on-reindex semantics and the metered/paid-plan cost caveat. It doesn't discuss failure modes, size limits, or indexing latency, so it's strong but not complete.
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 short clauses, each carrying distinct information: purpose, input shape plus replace semantics, and the metering caveat. Nothing is padded and the purpose leads.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-param write tool with no output schema, the description covers purpose, input mapping, replacement behavior, and cost implications. It omits what the agent should expect back or how errors/partial indexing surface, which keeps it off a 5.
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 only two required params, so the schema already documents both fields. The description's 'path → content map' phrasing restates what the files property says rather than adding format or edge-case detail. 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 ('Index a project's files for semantic code search (RAG)'), which clearly separates it from read-only siblings like search_project_code and clear_code_index. It stops short of naming an alternative explicitly, so it's clear but not fully sibling-differentiated.
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?
Implies use when you want code searchable via RAG, and notes that re-indexing a path replaces it, but never says when to choose this over search_project_code or clear_code_index. The 'metered — paid-plan feature' note is the closest thing to a prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your API keys — name, prefix, created/expiry dates and IP allowlist. Never returns the secret.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent and non-destructive behavior, so the description's main added value is the security guarantee 'Never returns the secret' plus the field inventory — genuinely useful context beyond the annotations. It stops short of noting pagination, ordering, or whether revoked keys appear.
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?
One em-dash-separated sentence: verb+resource first, returned fields second, security caveat last. No filler and nothing an agent must dig past.
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 input parameters and no output schema, the description carries the burden of describing what comes back, and it does so via the field list plus the secret-exclusion guarantee. Only gaps are pagination and whether revoked/expired keys are included.
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 tool takes zero parameters, so there is nothing to disambiguate beyond the baseline; the description correctly avoids inventing filter semantics that the empty schema contradicts.
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 ('List your API keys') and immediately enumerates the returned fields (name, prefix, created/expiry dates, IP allowlist), which clearly separates it from write-side siblings like create_api_key and revoke_api_key.
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 only implied by the verb 'list'; the description never says when to reach for this versus create_api_key/revoke_api_key, nor does it mention prerequisites such as needing an existing key set. An agent can infer the use case but gets no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your own audit trail — API-key, deployment and billing events where you were the actor, newest first. Needs a plan that includes audit logs; otherwise it returns an upgrade message.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 50 | |
| action | No | Only events with this action | |
| offset | No | Default 0 | |
| category | No | Only events in this category |
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 description's added value is the plan-gating behavior and the failure return path, plus ordering ('newest first'). It says nothing about pagination behavior across offset/limit, which is the main remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste, and the highest-value information (scope and ordering) is front-loaded before the plan caveat. Nothing is repeated from the structured fields.
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 list tool with a fully documented schema and no output schema, the description covers access gating, scope and ordering. It could have closed the loop on pagination semantics (defaults/max are only in the schema) but nothing an agent needs in order to call 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 all four parameters (limit, action, category, offset) are already documented in the schema. The description gestures at event categories ('API-key, deployment and billing events') but adds no filtering syntax or format guidance beyond what the schema provides, so baseline 3 is right.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource (list audit log) and narrows scope precisely: events 'where you were the actor' and 'newest first'. That scope distinguishes it from siblings like list_api_keys or list_builds, which return resources rather than actor-scoped event 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?
It states the precondition for use (a plan that includes audit logs) and what happens when that precondition fails (an upgrade message), which is real routing guidance. It does not explicitly name alternatives such as the upgrade tool, but the fallback path is implied clearly enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your recent AI builds across all projects, newest first, with status, model and the project each belongs to.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return (default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context: results span all projects, are sorted newest first, and carry status/model/project columns, which matters since there is no output schema. It does not say whether the list is bounded other than by limit.
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 front-loaded sentence that packs scope, ordering and returned fields with no filler. Every clause carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter read tool with an output schema absent, the description supplies the return-shape summary, which is the main gap. What remains unexplained is pagination behavior beyond limit and how far back 'recent' reaches.
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 sole parameter's default (20) is documented in the schema, so the baseline applies. The description adds nothing about limit, such as ordering constraints or whether larger values are expensive, so it neither helps nor hurts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource (list AI builds), states the scope (across all projects), the ordering (newest first), and the fields returned (status, model, owning project). That is enough to distinguish it from get_build_status, which handles a single build, and from list_projects.
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?
'Recent' implies this is the discovery/overview call and the project attribution hints at cross-project browsing, but there is no explicit when-to-use, no statement of what it excludes, and no pointer to siblings like get_build_status or cancel_build. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's saved checkpoints (up to 100, newest first) with label, changed paths and timestamp. Checkpoints are the project's version history — use one to undo a bad change.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts the annotations don't: the result is capped at 100 and ordered newest-first, which tells the agent there is no full-history enumeration and no pagination parameter to reach for.
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: capability and result shape first, then the conceptual meaning of a checkpoint and its purpose. Zero filler, and the most decision-relevant facts (cap, ordering, fields) are 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?
For a read-only, single-parameter list tool with no output schema, the description covers what is returned (label, changed paths, timestamp) and the size/ordering limit. It could go one step further by naming restore_checkpoint as the follow-up action, but nothing essential for calling 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?
Only one parameter and schema coverage is 100%, so the schema already explains 'id' as a Project UUID. Baseline for a single fully documented parameter is 4; the description adds nothing new about the parameter but loses nothing either.
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 ('List a project's saved checkpoints') and adds the scope and shape of results (up to 100, newest first, label/paths/timestamp). It implicitly distinguishes itself from restore_checkpoint by framing the listing as the way to 'undo a bad change', but never names the write sibling, so the differentiation is inferred rather than explicit.
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 line 'Checkpoints are the project's version history — use one to undo a bad change' implies the downstream action but doesn't say when to call list vs. restore_checkpoint, nor any prerequisite like needing a checkpoint id first. Usage is suggested, not instructed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the connectors available on MisarDev and whether each is enabled for you, with its category, status and dashboard path.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is clear without the description. The description adds useful return context ('whether each is enabled for you' plus metadata fields), but does not mention auth requirements, pagination, or rate 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?
A single front-loaded sentence with no wasted words. It covers purpose and key return fields efficiently.
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-parameter read-only list tool with rich annotations and no output schema, the description is largely complete: it names the resource and summarizes the returned attributes. The main gap is that it doesn't route the agent to toggle_connector for changes.
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 tool takes no parameters, so the baseline is 4. The empty schema means there is no parameter documentation burden on the description.
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 ('List') and resource ('connectors') and describes the returned fields: enabled status, category, status, and dashboard path. It is distinguishable from most siblings, though it does not explicitly contrast with toggle_connector, the likely mutation counterpart.
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 the tool returns but not when to use it versus alternatives. It never mentions toggle_connector, which is the obvious sibling for changing connector enablement, so the agent gets no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List your notifications (build finished, deploy failed, invitations…), newest first, with the unread count. Pass before (an ISO timestamp from the last row) to page back; unread_only=true returns just the count.
| Name | Required | Description | Default |
|---|---|---|---|
| before | No | ISO timestamp — return notifications older than this | |
| unread_only | No | Return only { unreadCount } |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered; the description adds real behavior beyond that — default ordering (newest first), that unreadCount is bundled into normal responses, and that unread_only collapses the response to only the count. It omits page size / result limits, which is the main remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact clauses, no filler, with the primary purpose and ordering front-loaded before the parameter guidance. Every sentence 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?
For a two-optional-parameter read tool with annotations covering safety and no output schema, the description supplies ordering, count semantics, and pagination. Only pagination limits (page size, max rows per call) are unstated, which is a minor omission.
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 earns above baseline by explaining where the `before` value comes from ('an ISO timestamp from the last row') — a cursor-sourcing detail absent from the schema — and reinforcing the shape-switching effect of unread_only.
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?
Uses a specific verb+resource ('List your notifications') and immediately enumerates the content types (build finished, deploy failed, invitations), ordering (newest first), and an included aggregate (unread count). This clearly separates it from the sibling mutation tools mark_notification_read and mark_notifications_read.
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 invocation guidance for both parameters: pass `before` from the last row to page back, and use unread_only=true to get just the count. It does not, however, explicitly state when to prefer this over mark_notifications_read or any other sibling, so routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List MisarDev's plans with prices, limits and features — what each upgrade would unlock.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations fully cover the safety profile: readOnlyHint=true, destructiveHint=false, openWorldHint=false, and idempotentHint=true. The description adds useful context about the returned plan attributes (prices, limits, features), which matters since there is no 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?
It is a single, front-loaded sentence with no waste. The key action and returned content are conveyed immediately.
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 no-parameter, read-only listing tool with rich annotations and no output schema, the description is largely complete: it says what the returned plans include. Minor gaps such as ordering or pagination are not relevant without parameters.
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 tool takes zero parameters and the schema is empty. Per the rubric, zero parameters gives a baseline of 4, and no additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (List) and resource (MisarDev's plans) and specifies the contents returned: prices, limits, and features. It does not explicitly name sibling tools such as get_subscription or upgrade, so differentiation is implied 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?
The phrase 'what each upgrade would unlock' hints this tool is used to inspect plan options before upgrading, but it does not explicitly say when to use it versus get_subscription, get_usage, or upgrade. Usage context is implied, not defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the projects you own or can access, newest first, with cursor pagination. view=active (default) hides archived and trashed projects; pass view=archived or view=trash to see those.
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Which lifecycle view to list (default active) | |
| limit | No | Results per page (default 20, max 100) | |
| cursor | No | Project ID to start after (from the previous page) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations: ordering ('newest first'), pagination ('cursor pagination'), and view semantics (what active/archived/trash mean).
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 core purpose and followed by key lifecycle-view details. Every sentence earns 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?
Given the simple list operation, full schema coverage, and annotations covering safety, the description is complete enough for an agent to call it correctly. It covers ordering, pagination, and view filtering; no output schema means no obligation to describe return values.
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. The description adds meaning for the 'view' parameter by explaining that active hides archived/trashed and that archived/trash reveal them, which the schema does not fully clarify.
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 ('List') and resource ('projects') with scope ('you own or can access'). Clear enough to distinguish from get_project, but does not explicitly name alternatives, so it misses full sibling differentiation.
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?
Describes view behavior and defaults, implicitly indicating usage for enumerating projects. However, it offers no explicit when-to-use vs alternatives (e.g., get_project, search_workspace) or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the starter templates a new project can begin from, with their IDs, names and categories. Pick one here before calling use_template.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is settled. The description adds genuinely new context: what a result record contains and that selection precedes use_template. No output schema exists, and pagination/ordering behavior is unmentioned, 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 sentences, each earning its place: the first defines the resource and payload, the second gives the next action. Front-loaded with the purpose and no redundant restatement 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?
For a zero-parameter list with no output schema and rich annotations, the description covers purpose, returned fields, and downstream workflow. Only minor details (ordering, whether the list is ever filtered) are absent, and they are unlikely to block a correct call.
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 tool takes no parameters, so the baseline is 4. The description correctly implies no input is required rather than inventing filtering options, and nothing in the schema needs compensating for.
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 the starter templates') plus the scope ('a new project can begin from') and the fields returned (IDs, names, categories). It also positions itself in the workflow relative to use_template, so an agent can tell it apart from that sibling 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?
Explicitly sequences the tool as a prerequisite: 'Pick one here before calling use_template.' That is clear when-to-use guidance. It stops short of naming exclusions (e.g., when to call get_template for a single template's details instead), so it falls just 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.
Look up a domain's public registration data (RDAP): whether it is registered, its registrar and key dates. Useful before suggesting a custom domain.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Domain name, e.g. example.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety and external-network profile is covered structurally. The description adds that the source is public RDAP data and lists the fields returned, but says nothing about rate limits, behavior for unregistered or malformed domains, or latency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the action and returned data front-loaded, followed by a single sentence of usage context. Nothing is redundant or padded.
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 lookup with no output schema, the description does the job: it names the data source and summarizes the return fields, reducing the need for an output schema. It stops short of covering failure modes (domain not found, RDAP lookup errors) which would complete 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?
There is a single required parameter with 100% schema description coverage and an inline example (example.com). The description adds no format constraints (TLD handling, IDN, subdomain acceptance) beyond what the schema already supplies, 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 ("Look up a domain's public registration data (RDAP)") and enumerates what it returns: registration status, registrar, key dates. It does not explicitly distinguish itself from close siblings like check_subdomain or get_custom_domain, which keeps it below a 5.
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?
"Useful before suggesting a custom domain" implies a usage scenario, but there is no explicit when-not guidance and no named alternative among the several domain-related siblings (check_subdomain, get_custom_domain, set_custom_domain). The agent must infer which domain tool fits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark one notification as read (use mark_notifications_read for all of them).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Notification ID (from list_notifications) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey the important behavior: idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds only the singular-vs-bulk scope, and says nothing about what happens when the notification is already read, permission requirements, or the response. With annotations covering the safety profile, this is adequate but thin.
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?
One sentence, front-loaded with the action and ending with the disambiguation clause. Nothing superfluous.
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 trivial one-parameter, idempotent mutation with full annotation coverage and no output schema, the description gives everything needed to invoke it correctly. A brief note on the return (e.g. updated notification) is the only 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 100% and the single id parameter is documented in-schema with its source ("from list_notifications"). The description adds no format or sourcing detail beyond that, so it sits at the baseline where the 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?
States a specific verb plus singular resource ("Mark one notification as read") and immediately scopes it against the bulk sibling mark_notifications_read. An agent can distinguish it from the sibling 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?
The parenthetical explicitly names the alternative tool and the condition that selects it ("for all of them"), which is exactly the single-vs-bulk routing decision the agent needs. No ambiguity remains about which tool to pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark every notification as read, clearing the unread badge. Nothing is deleted.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false and idempotentHint=true, and the description reinforces this with 'Nothing is deleted' plus describes the visible effect ('clearing the unread badge'). That effect is genuinely useful context beyond the annotations, though the no-deletion note partially restates destructiveHint=false.
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 short sentences, front-loaded with the action and scope, then the effect. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A zero-parameter bulk mutation with rich annotations and no output schema needs little else. The description covers action, scope, side effect, and non-destructiveness, which is fully adequate for this complexity level.
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?
There are zero parameters, so the schema carries no semantic burden and there is nothing for the description to disambiguate. Baseline 4 applies for a no-param tool.
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 ('Mark every notification as read') with clear scope ('every') that distinguishes it from the singular mark_notification_read sibling. It stops short of explicitly naming that sibling, but the scope word does the differentiation.
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 word 'every' implies bulk usage versus the single-item variant, but the description never explicitly says when to use this instead of mark_notification_read or list_notifications. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision the database backend for a full-stack project: its own isolated schema, protected by row-level security. Safe to repeat — an already-provisioned project reports its existing backend.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the bar is lower. The description still adds real value: it says what is actually created (isolated schema with row-level security) and what a repeat call returns (the existing backend) rather than erroring — behavior an agent needs to interpret results. It does not cover auth requirements or latency of provisioning.
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 short sentences, front-loaded with the action and its effect, followed by the repeat-safety caveat. Nothing is redundant or padded.
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 provisioning tool with no output schema, the description covers the side effect, safety profile, and repeat behavior adequately. Missing only minor context such as prerequisites or whether provisioning is asynchronous.
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?
There is a single parameter with 100% schema description coverage ('Project UUID'), so the schema fully documents it. The description adds no further semantics about the id (e.g., that the project must exist), which is the baseline for high-coverage schemas.
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 (provision the database backend) and adds concrete scope: an isolated schema with row-level security. It does not name the nearest sibling get_project_backend, so the boundary with a pure read of the backend is only implied by the 'safe to repeat' 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 'safe to repeat' note implies you can call it defensively, but there is no explicit when-to-use guidance, no prerequisite (project must already exist), and no contrast with get_project_backend or create_project. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detach a project's custom domain and remove its route. The domain stops serving the app immediately; the default subdomain keeps working. Confirm with the user first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds real value on top: the domain stops serving immediately, the default subdomain keeps working, and the user should be confirmed first – details the annotations 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?
Three short sentences, front-loaded with the action, followed by the effect and the confirmation caution. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, one fully documented parameter, and no output schema, the description covers what the agent needs to call it responsibly. Only the sibling-routing guidance is thin.
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?
There is a single required 'id' parameter with 100% schema coverage describing it as a Project UUID. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Detach a project's custom domain and remove its route'), which clearly separates it from set_custom_domain and get_custom_domain. It does not explicitly name a sibling, but the destructive detach framing is 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?
Usage is implied by context (detaching a domain, default subdomain unaffected) plus the caution 'Confirm with the user first', but the description never says when to prefer this over set_custom_domain or update_project_subdomain, leaving routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give a checkpoint a human-readable label (1–80 characters) so it is easy to find later.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | New label, 1–80 characters | |
| checkpoint_id | Yes | Checkpoint ID (from list_checkpoints) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so re-running is safe and non-destructive. The description adds the useful motivation and constraint but does not say what happens to the previous label or that the checkpoint must already exist.
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 front-loaded sentence that states the action, the constraint, and the rationale with zero waste.
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 two-parameter rename tool with full schema coverage and rich annotations, the description covers what an agent needs. Only minor gaps remain, such as behavior when the checkpoint ID is invalid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented in the schema, including the 1–80 character range that the description merely repeats. Baseline 3 is appropriate since the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: giving a checkpoint a human-readable label with the 1–80 character bound. This clearly distinguishes it from list_checkpoints and delete_checkpoint by name/action, though it does not explicitly contrast with 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 phrase 'so it is easy to find later' implies the motivation to use it, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as delete_checkpoint or restore_checkpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a project's files to a checkpoint. The current state is snapshotted first, so the restore itself can be undone — but it does overwrite the working files, so confirm with the user. A published site does not change until you deploy again.
| Name | Required | Description | Default |
|---|---|---|---|
| checkpoint_id | Yes | Checkpoint ID (from list_checkpoints) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds genuinely non-obvious nuance: the current state is snapshotted first so the restore is reversible, working files are overwritten, and the live site is unaffected until a deploy. That is exactly the extra context structured fields 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?
Three tight sentences, front-loaded with the action, then the safety caveat, then the deployment scope. Every sentence carries distinct information with no repetition of the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive single-param tool with no output schema, the description covers side effects, reversibility, and blast radius well. It doesn't say what the call returns (e.g. a snapshot/restore identifier) or how long the operation takes, which is a minor 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 100% and the single parameter already documents its source ('from list_checkpoints'), so the schema carries the burden. The description adds no format or sourcing detail beyond it — baseline 3.
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 ('Restore a project's files to a checkpoint') so the action is unambiguous. However, it does not differentiate itself from the sibling restore_project, which an agent could plausibly confuse with checkpoint restoration, so it falls short of a 5.
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 — confirm with the user, and a published site won't change until redeploy — which tells the agent how to behave before invoking. It stops short of naming alternatives (e.g. delete_checkpoint for discarding, restore_project for whole-project recovery) or stating when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a project from the trash. A project that was archived before it was trashed returns to the archive, not to the active list.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation is non-destructive and idempotent. The description adds valuable behavioral context by explaining where the restored project is placed depending on its prior archived state, though it does not mention permission requirements.
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 with no wasted words. The primary action is front-loaded, followed directly by the important archived-state distinction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter restore operation with annotations covering safety and idempotency, the description is complete enough. It explains the key behavioral nuance and does not need to explain return values because 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?
Schema coverage is 100% and the single `id` parameter is fully documented in the schema as a project UUID from `list_projects`. The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 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?
The description states a specific verb and resource: restore a project from the trash. It clearly distinguishes the resource from sibling tools like restore_checkpoint, though it does not explicitly name alternatives or siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly implies the tool is used when a project is in the trash and adds a useful condition: projects archived before being trashed return to the archive. It does not explicitly state when not to use it or name alternative tools such as restore_checkpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke an API key by ID. It is deleted permanently and anything still using it fails immediately. Confirm with the user first, and never revoke the key this session is using without saying so.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | API key ID (from list_api_keys) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that deletion is permanent, that anything still using the key fails immediately (blast radius), and that the user must be consulted plus a special warning about self-revocation. These are operational consequences an agent cannot infer from destructiveHint=true 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?
Three short sentences, front-loaded with the operation, then consequence, then safety rule. No filler or repetition of annotation data.
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-required-parameter destructive tool with a fully documented schema and no output schema, the description covers purpose, irreversibility, impact, and required user confirmation. Nothing needed to call 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 description coverage is 100%, and the schema already says the ID comes from list_api_keys. The description's only addition is 'by ID', which adds no syntax or format detail; baseline 3 applies since the schema carries the parameter semantics.
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 ('Revoke an API key by ID') and immediately clarifies the effect is a permanent deletion, which distinguishes it from the sibling create_api_key and from non-destructive operations. An agent can identify the operation and its consequence without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit procedural guidance: confirm with the user first, and explicitly flag the case of revoking the session's own key. It does not name an alternative tool, but for a destructive singleton there is no meaningful alternative to route to, so the guidance is close to complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search inside an indexed project's code. Answer only from the snippets it returns and cite their file paths; if get_code_index_stats shows nothing indexed, index first.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language search query | |
| project_id | Yes | Project UUID |
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 genuine behavioral context beyond them: results are snippets to ground answers in, file paths must be cited, and an index must exist first.
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, zero waste, purpose front-loaded before the grounding instruction and the indexing prerequisite. Every clause 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?
For a two-parameter read tool with no output schema, the description covers purpose, prerequisite, and the nature of the return (snippets with file paths). Only the result shape or result-count behavior is left unstated, which is minor.
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% — query (natural language) and project_id (UUID) are already documented in the schema. The description adds nothing parameter-specific, 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: "Semantic search inside an indexed project's code." The word "semantic" plus "indexed" distinguishes it from literal file listing (get_project_files) and from the write-side index_project_code, though it never names those siblings explicitly.
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 a concrete precondition workflow: check get_code_index_stats and index first if nothing is indexed, which names the sibling to consult. It stops short of explicitly excluding alternatives like search_workspace or get_project_files, so the routing guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across your projects and the public catalogue (templates, skills, the published gallery) by name and description. Does NOT search inside project files — use search_project_code for that. A source that could not be reached is reported as unavailable, never as zero results.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows across all sources (default 20, max 50) | |
| query | Yes | Search term (very short terms return an empty answer) | |
| types | No | Comma-separated subset of project,template,skill,gallery (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds a genuinely useful failure-mode guarantee that an agent could not infer — unreachable sources are reported as unavailable rather than as zero results, preventing false negatives. It stops short of describing result ordering or how mixed-source rows are merged, which is the only remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each doing distinct work: positive scope, explicit exclusion with alternative, then a failure-mode caveat. Scope is front-loaded and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 params at full schema coverage, no output schema, and annotations carrying the safety profile, the description covers scope, exclusion, and error semantics well. The one thing an agent might still wonder — whether results are interleaved across sources or returned per type — is only obliquely implied by the schema's "rows across all sources" wording.
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 query, types, and limit are already documented with defaults and bounds in the schema itself. The description reinforces what is searched (name and description) but adds no syntax, format, or combinatorial guidance beyond the structured fields, 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 (search) and an explicit resource scope: projects plus the public catalogue (templates, skills, gallery), matching by name and description. It immediately distinguishes itself from the closest sibling by naming search_project_code as the tool for file contents.
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 an explicit negative condition ("Does NOT search inside project files") paired with the named alternative to use instead, which is exactly the routing signal an agent needs. The catalogue-vs-project scope plus the types parameter give a complete picture of when this tool is the right pick.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a domain the user owns to a published project and provision routing/TLS. Paid plans only (the API answers with an upgrade offer otherwise). Returns the DNS record to set — the domain only serves once that record is live.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID | |
| domain | Yes | Domain to attach, e.g. app.example.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: discloses plan gating and the failure mode (upgrade offer), discloses the side effect (routing/TLS provisioning), discloses the return value (the DNS record to set), and discloses the activation condition (domain only serves once the record is live). This is exactly the behavioral context annotations cannot express.
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 dense sentences, zero filler, with the core action front-loaded and the gating/return/activation details following in priority order. Every sentence carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with no output schema, the description covers action, prerequisites, error behavior, return payload, and when the result takes effect. Nothing required to call it correctly or interpret the result is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds one genuine constraint not in the schema — the domain must be one the user already owns — but gives no format guidance beyond the schema's 'app.example.com' example.
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+resource: 'Attach a domain the user owns to a published project and provision routing/TLS' — an agent immediately knows this writes a custom-domain binding plus TLS routing. It implicitly separates itself from get_custom_domain, remove_custom_domain and update_project_subdomain, though it never names those alternatives.
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?
Preconditions are stated up front: paid plan required ('the API answers with an upgrade offer otherwise') and the project must be published. It does not explicitly route the agent to remove_custom_domain or update_project_subdomain, but the read/write/subdomain split is inferable from the wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable a connector by slug (from list_connectors). Reversible.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Connector slug (from list_connectors) | |
| enabled | Yes | true to enable, false to disable |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotent, non-destructive, and non-read-only behavior. The description adds 'Reversible,' a meaningful behavioral trait beyond the annotations, though it omits details like immediate effect or permission requirements.
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 short sentences, front-loaded with the action. 'Reversible' is a compact, useful addition 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?
For a simple two-parameter toggle with full schema coverage and annotations, the description covers purpose, slug source, and reversibility. Only immediate-effect or permission details are missing, which is minor.
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 fully documents both parameters. The description repeats the slug source and enable/disable mapping without adding syntax or format 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?
States the specific verb (enable/disable) and resource (connector), and explicitly points to list_connectors as the source of the slug, which distinguishes it from that read-only sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the action, but there is no explicit when-to-use, when-not-to-use, or alternative guidance. The parenthetical '(from list_connectors)' is a parameter hint, not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a published site offline. Its public URL stops serving immediately. This is not a rollback — to go back to an earlier version, restore_checkpoint and deploy again. Confirm with the user first.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool destructive, idempotent, and open-world, but the description adds important behavioral context: the public URL stops serving immediately, the action is not a rollback, and the user should confirm first. These details go meaningfully beyond the structured 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 four short sentences, front-loaded with the core action and immediate effect, followed by the rollback distinction and confirmation instruction. There is no wasted text.
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 one-parameter destructive lifecycle tool, the description plus annotations and schema provide enough context to invoke it correctly. It covers immediate effect, non-rollback semantics, alternative workflow, and user confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single 'id' parameter already has a clear description in the schema ('Project UUID (from list_projects)'). The description does not add parameter-specific guidance, so the baseline of 3 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?
The description states a specific verb and resource: 'Take a published site offline.' It also distinguishes the action from rollback, which helps the agent understand exactly what this tool does versus related lifecycle operations.
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 indicates when to use this tool ('Take a published site offline') and when not to use it for version rollback, naming restore_checkpoint and deploy_project as the alternative path. It also explicitly says to confirm with the user first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a project's name, description, files, settings or visibility. Files passed here REPLACE the matching paths. Pass the version you read with get_project to avoid overwriting someone else's newer edit (the API answers 409 on a conflict).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID (from list_projects) | |
| name | No | New project name | |
| files | No | File map to write: path → content | |
| version | No | Version read from get_project, for conflict detection | |
| settings | No | Updated settings | |
| is_public | No | Make the project public (true) or private (false) | |
| description | No | New description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotent=true and destructive=false, and the description adds the two facts an agent most needs: that 'files' REPLACES matching paths rather than appending, and that stale versions yield a 409 conflict response. These are non-obvious behavioral traits not derivable from the annotation set.
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 mutable surface, then the highest-risk semantic (replace) and the concurrency contract. No filler or restatement of the name/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 7-param mutation with a nested file object and no output schema, the description covers the two dangerous behaviors (overwrite and conflict). It leaves unstated whether omitted fields are left unchanged and what the response contains, minor gaps given the 100% schema coverage.
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 earns above that by clarifying replace semantics for 'files' (path → content map that overwrites) and the read-then-pass workflow for 'version', which the schema terse line only hints at. It adds nothing for 'settings' or 'is_public', which the schema already covers.
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 (update) and resource (project) and enumerates the mutable surface: name, description, files, settings, visibility. It does not name or route against the closest sibling, write_project_files, which also writes file content, so an agent must still infer 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?
Gives concrete usage instruction for the version parameter: read it via get_project first, and expect a 409 on conflict. It stops short of exclusions or alternatives, giving no guidance on when to prefer write_project_files or update_project_knowledge over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a project's knowledge (up to 20,000 characters) — the standing notes the AI builder reads on every change. This replaces the whole text, so read it with get_project_knowledge first and send the edited version.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID | |
| content | Yes | The full knowledge text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the key missing detail: it replaces the WHOLE text, not a partial edit, and therefore requires a read-modify-write cycle to avoid data loss. It also states the 20,000-character ceiling. It stops short of describing what happens on failure or whether prior versions are recoverable, so not 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 tightly written sentences. The destructive whole-replacement semantics are front-loaded, and the read-first workflow follows immediately. 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?
For a two-parameter tool with full schema coverage, no output schema, and annotations covering the safety profile, the description supplies exactly the missing pieces: what the resource means and the mandatory read-before-write sequence.
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 parameters are documented; the baseline is 3. The description adds genuine semantics by clarifying that 'content' must be the entire replacement text rather than a delta, which changes how an agent constructs the argument.
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 'Replace' plus the resource 'project's knowledge', and it goes further by explaining what that resource is ('the standing notes the AI builder reads on every change'). This lets an agent distinguish it from get_project_knowledge, which it names explicitly, 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?
Explicit workflow instruction: read with get_project_knowledge first, then send the edited version. It names the sibling to use for the read step and describes the exact sequencing, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a project to a new .misar.app address (check it first with check_subdomain). If the app is published, the live site moves immediately and the OLD address stops working — get the user's explicit approval. If it is not published yet, this just reserves the name for the next deploy.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID | |
| subdomain | Yes | New subdomain, without .misar.app |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true but don't explain the consequence; the description supplies it precisely—the old address stops working and the live site moves immediately, versus merely reserving the name when unpublished. This is exactly the behavioral context beyond the annotation flags.
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 dense sentences, zero waste, front-loaded with the core action then the consequence and the approval gating. Every clause earns 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?
For a 2-param tool with full schema coverage, no output schema, and annotations carrying the safety profile, the description covers the essential unknowns: irreversibility of the live move, the prerequisite check, and the approval requirement. Nothing an agent needs to call 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% and both params are documented ('Project UUID', 'New subdomain, without .misar.app'). The description's '<subdomain>.misar.app' phrasing reinforces the format but adds little beyond what the schema already states; baseline 3 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 ('move') and resource ('a project to a new <subdomain>.misar.app address'), clearly distinguishing this rename-subdomain operation from siblings like set_custom_domain or update_project. An agent can select it 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 prerequisite alternative ('check it first with check_subdomain') and gives a conditional rule: get explicit user approval when the app is published. Both when-to-use and a critical gating condition are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the current MisarDev plan, how much of each quota (builds, edits, projects) is left this period, and the link to compare plans and upgrade. Call it any time — not only after hitting a limit. Reads only: it never changes the plan or takes payment. On a local install, open=true also opens the pricing page in the user's browser.
| Name | Required | Description | Default |
|---|---|---|---|
| open | No | Local installs only: also open the pricing page in the browser. The hosted server returns the link instead. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the hints, explicitly guaranteeing that the tool 'never changes the plan or takes payment.' It also details the side effect of the local install flag on the `open` parameter.
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 slightly verbose but highly effective. Every sentence addresses a specific functional, safety, or usage aspect, ensuring the complexity of the tool is handled without excessive fluff.
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 simplicity of the schema and annotations, the description provides all necessary context: what data it returns (plan/quotas/link), what it does not do (no payment/changes), and how it behaves in different environments.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description isn't required to explain parameters, but it provides valuable operational semantics for the single input. It clarifies that the 'open' parameter's function changes based on whether the environment is local or hosted, linking the parameter's intent to its runtime effect.
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 the tool's purpose: showing the current MisarDev plan, the remaining quotas for specific resources (build, edits, projects), and providing the link to upgrade. It clearly delineates this status check from the actual upgrade action, distinguishing it from other modification siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides crucial temporal guidance by stating the tool should be called 'any time — not only after hitting a limit,' which dictates when the agent can reasonably invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project from a template. Returns the new project; counts against the plan's project quota.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Template ID (from list_templates) | |
| name | Yes | Name for the new project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds two useful behavioral facts: it returns the new project and it counts against the plan's project quota. The quota impact is important context for a mutating tool, though permissions and failure behavior are still undocumented.
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 tight sentences with the action front-loaded and no wasted wording. Both the creation purpose and the quota/return note earn their 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?
For a simple two-parameter creation tool with full schema coverage and clear annotations, the description covers the essential purpose, return value, and quota impact. It stops short of explaining failure modes or explicitly routing among sibling creation tools.
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 both parameters are fully described in the schema. The description adds no additional parameter meaning beyond the schema, so the baseline 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 states a specific verb and resource: 'Create a new project from a template.' This clearly distinguishes template-based creation from a blank create, although it does not explicitly name siblings like create_project or duplicate_project.
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?
There is no explicit guidance on when to use this tool instead of create_project, duplicate_project, or other project creation paths. The only implied prerequisite is that the 'id' comes from list_templates, which is already documented in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Answer a question from the live web with citations (MisarDev's grounded search). Returns the answer, url_citation annotations and the ranked sources. Spends model credits; quote only what the sources support.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The question or search query | |
| search_context_size | No | How much web context to gather (default medium) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, openWorld, not idempotent), so the description's real contribution is economical/behavioral: it consumes model credits and returns an answer plus url_citation annotations and ranked sources. That is meaningful context an agent cannot get from the enum and hints. It stops short of saying whether results are cached or how large the response can get, so not 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 tight sentences, front-loaded with the capability and the return shape, ending on the constraint. "MisarDev's grounded search" is minor branding that costs a few words without adding agent-relevant information, but nothing else is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only two parameters, full schema coverage, and no output schema, the description fills the main gap by enumerating the return payload (answer, citations, ranked sources). What remains unstated is failure behavior — what happens when no sources are found — which matters for a grounded-answer 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%, so both parameters are already documented with the enum and its default. The description adds nothing about how query phrasing or search_context_size tradeoff affects results — the grounding note applies to output, not inputs. 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 description leads with a specific verb and scope: "Answer a question from the live web with citations." The qualifier "live web" implicitly separates it from the workspace/project-code search siblings, and "grounded search" frames the mechanism. An agent can tell what this does 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?
"Spends model credits" and "quote only what the sources support" give a cost/grounding caveat, which implies this is the pricier option to use deliberately. However, no alternative is named — nothing tells the agent to prefer search_workspace or search_project_code for internal content instead. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create, update or delete files in a project (1–100 per call, each up to 1 MB; paths are relative, no ..). Other files are left as they are. Overwrites and deletes are applied to the working files immediately — confirm with the user, and use list_checkpoints/restore_checkpoint to undo. Pass version (from get_project) to refuse the write if anything changed since you read it. The published site does not change until you deploy again.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project UUID | |
| files | Yes | Files to write | |
| version | No | Optional: the project version you last read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the destructiveHint=true annotation by spelling out what is actually destroyed (overwrites and deletes hit working files immediately), what is preserved (other files untouched), how to recover (checkpoints), the optimistic-concurrency behavior of `version`, and the fact that the published site is unaffected until redeploy. Each sentence adds context an agent cannot get from 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?
Five tight sentences, front-loaded with the capability, then constraints, then the safety and recovery path, then the deploy caveat. No restatement of the tool name or filler; every clause carries 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 destructive multi-file mutation with no output schema, the description covers limits, path rules, partial-application scope, reversibility, concurrency, and downstream deployment effects — everything needed to invoke it safely without reading other docs.
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 100%, so the baseline would be 3, but the description adds constraints absent from the schema: the 1 MB per-file cap, the ban on `..` in paths, and the refuse-if-changed semantics of `version`. It does not explain the `action` default or content-for-delete convention, which the schema already covers.
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 set and resource: 'Create, update or delete files in a project', plus concrete scope (1–100 files, 1 MB each, relative paths). This clearly separates it from read-side siblings like get_project_files and from deploy_project, which the description explicitly says is unaffected.
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 actionable routing: confirm with the user before applying overwrites/deletes, use list_checkpoints/restore_checkpoint to undo, and pass `version` from get_project to guard against concurrent changes. It stops short of explicitly naming a read alternative (e.g. 'use get_project_files to read'), so the contrast is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
archive_projectcancel_buildcheck_subdomainclear_code_indexcreate_api_keycreate_chat_completioncreate_projectdelete_checkpointdelete_projectdeploy_projectduplicate_projectget_build_statusget_code_index_statsget_custom_domainget_deployment_statusget_projectget_project_backendget_project_filesget_project_knowledgeget_subscriptionget_templateget_usageimport_artifactindex_project_codelist_api_keyslist_audit_loglist_buildslist_checkpointslist_connectorslist_notificationslist_planslist_projectslist_templateslookup_domainmark_notification_readmark_notifications_readprovision_project_backendremove_custom_domainrename_checkpointrestore_checkpointrestore_projectrevoke_api_keysearch_project_codesearch_workspaceset_custom_domaintoggle_connectorunpublish_projectupdate_projectupdate_project_knowledgeupdate_project_subdomainupgradeuse_templateweb_searchwrite_project_filesDeploy apps to servers you own: projects, deployments, logs, health and pull request previews.
Deploy sites and apps from your AI coding agent: domains, DNS, logs, env, versions and rollback.
Deploy and manage applications, databases, domains, and git repos
Deploy your project to a live HTTPS URL from your AI tool; read logs, set variables, resize apps.
Add one secure layer between your agents and this server.
