furrow-forms

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

Annotations already indicate destructiveHint=true and idempotentHint=true, and the description adds value by clarifying that this is not a hard delete and that archiving is irreversible in v1. This contextualizes the destructive behavior beyond what the annotations alone convey. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The primary action is front-loaded, and the critical caveats about hard delete and lack of unarchive follow immediately. 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 tool with annotations covering safety and idempotency, the description covers the core action and the key irreversibility constraint. It does not detail post-archive effects or return values, but the tool is simple and has no output schema, so the information is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the only parameter, client_id, already has a clear schema description including its source ('Client id from list_clients or create_client'). The tool description adds no additional parameter-level meaning, 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: 'archive a client.' It further distinguishes the operation from a hard delete and notes that no unarchive tool exists in v1, so an agent can clearly tell what this tool does and what it does not do.

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 gives clear usage context: use it to archive, and do not treat it as a hard delete. It also warns that there is no unarchive tool in v1, signaling irreversibility. It does not explicitly name alternative tools or conditions for choosing them, but the exclusions are clear enough.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds meaningful behavioral context by explaining the specific effect on public submissions (404) and clarifying that this is not a hard delete, which refines what 'destructive' means in this 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?

The description is two sentences with no filler. The primary purpose is front-loaded in the first sentence, and the cautionary note about hard deletion is brief and directly relevant.

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 tool with annotations and no output schema, the description gives the core functional behavior and a key exclusion. It does not explain side effects beyond the 404 outcome, but given the simplicity and annotations, it is sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage: form_id is described with a clear description and format. The description itself does not add parameter-level information, 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 ('archive'), the resource ('a form'), and the concrete outcome ('public submit returns 404'). It clearly distinguishes from siblings like archive_client and archive_project by focusing on forms, and from hard delete via the explicit 'Do not use this as a hard delete' note.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool ('Use to archive a form so public submit returns 404') and when not to use it ('Do not use this as a hard delete'). This gives the agent clear positive and negative usage conditions without needing to infer them.

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

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

Annotations already signal destructive and non-readonly behavior, and the description adds valuable context beyond that: archiving blocks public submissions and cannot be undone in v1. This directly informs the agent about irreversible consequences, which is exactly the kind of behavioral detail needed.

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 with no filler: purpose, side effect, and irreversibility warning are all front-loaded. 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 tool with a well-described schema and annotations already covering safety and idempotency, the description is complete. It tells the agent what happens, what not to use it for, and what cannot be done afterward.

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 input schema already fully documents project_id with format, pattern, and valid sources (list_projects, create_project, bootstrap_site). The description adds no parameter-specific detail, so the baseline 3 applies because 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?

The description states a concrete verb and resource ('archive a website') and gives the key consequence ('Archived projects reject public submit'), so an agent can recognize it as the project-archiving action. It does not explicitly differentiate from sibling tools like archive_client or archive_form, but 'website' and 'projects' make the intended resource reasonably clear.

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 clear when-to-use context: use it to archive a website, and it explicitly warns not to treat it as a hard delete. It also notes the critical v1 limitation that no unarchive tool exists. It stops short of naming alternative tools or specifying when to prefer update_project or archive_client, but the guidance is still actionable.

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

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

Annotations only mark this as a mutating, idempotent call; the description fleshes out idempotency ('Idempotent on client, project, and form slugs'), plus auth, plan limits, token defaults, field-name bracket rules, and upload/download warnings. These are meaningful behaviors not visible in the annotations. No contradiction with readOnlyHint=false or idempotentHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, but it is an unusually long block of prose with no structuring. Most sentences carry useful operational detail, yet some constraints (e.g., the [] suffix rule) duplicate schema descriptions, making it denser than strictly necessary.

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 large input schema and absence of an output schema, the description covers required auth, plan limits, idempotency, form-field semantics, uploads, and security warnings. It leaves the broader response shape unspecified beyond plan_limit and the webhook_secret generation noted in the schema, which is a minor gap for a resource-creating 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?

Schema coverage is 100%, so the baseline is already high. The description adds value by explaining the name/slug client relationship, project_name/project_slug defaulting, team_id requirements, and crucial field-name array behavior for HTML vs JSON submissions beyond the individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action and resource set: 'stand up a client, one website (project), and its forms in a single call.' It distinguishes this bundled tool from update_form by explicitly saying 'Do not use when you only need to patch an existing form.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use ('Use this to stand up...'), a when-not rule ('Do not use when you only need to patch an existing form — call update_form'), and an error-path alternative ('call create_upgrade_link if bootstrap_site returns plan_limit'). It also specifies token scoping for team_id, which is a precondition for correct invocation.

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

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

Annotations supply idempotentHint=true, and the description elaborates on the strict flag and slug-based idempotency. It adds operational context about operator vs team-scoped token behavior and the client/project boundary, which goes 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?

Five sentences, each carrying distinct operational information with no filler. Core purpose and alternatives are front-loaded, and the caution about Turnstile/webhooks closes the definition without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter creation tool with no output schema, the description covers idempotency, auth requirements, cross-tool selection, and data placement. It does not describe the return value, but the rich schema and annotations already handle most invocation details.

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 meaning by tying slug to idempotency ('Idempotent on slug unless strict is true'), explaining team_id comes from list_teams, and clarifying that team-scoped tokens cannot target another workspace.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Use to add a client (company) by slug', naming a specific verb and resource, and immediately distinguishes this from bootstrap_site. It clearly states the tool's place relative to 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 explicitly says 'Prefer bootstrap_site when also creating a website and forms', providing a direct alternative condition. It also gives token-scoping rules for when team_id is required, and tells the agent not to put Turnstile/webhooks on a client because those belong on the project.

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

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

Annotations only declare write and idempotent behavior, but the description goes far beyond them: it explains how idempotency is affected by strict, how nullable overrides inherit project settings, multi-value [] suffix rules, JSON vs formData submission behavior, multipart file handling, and the security caveat about files_url. This is substantial behavioral disclosure with no contradiction.

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 dense and front-loaded with the core purpose, followed by inheritance rules and complex field-contract semantics. It is longer than a minimal definition, but every sentence carries functional information necessary for correct invocation. A slight structural split into paragraphs would improve scannability.

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?

The description covers prerequisites, idempotency, override inheritance, field naming traps, multi-value submission, file uploads, and download-folder security. It does not describe the create response shape, but no output schema exists and required fields are already in the schema. This is a minor gap for a tool this complex.

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?

Although schema description coverage is 100%, the description adds meaning not present in the schema: bracket conventions for multi-value HTML fields, the Object.fromEntries pitfall, formData.getAll usage for JSON mode, the file-upload multipart requirement, and the fact that field labels appear in notification emails. This materially improves correct parameter construction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'add a form under an existing project_id.' This clearly identifies the creation action and distinguishes it from update, get, list, and archive tools. The idempotency-on-slug note further defines the tool's exact purpose.

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 gives clear operational context such as 'under an existing project_id,' nullable overrides inheriting project settings, the strict idempotency switch, and the upload prerequisite. It does not explicitly name sibling alternatives like update_form or list_forms, but the usage context is unambiguous enough for an agent to select this tool properly.

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

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

Even though idempotentHint is already annotated, the description adds important caveats: idempotent on slug unless strict is true, plan_limit error signaling, free-account footer_mode restrictions, and token rendering behavior where missing fields render empty and never error. It also warns not to pass HTML and not to expose the files URL in a public snippet.

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 accurate and dense but not concise; it is a long block of prose covering plans, upgrade links, email tokens, uploads, and branding, much of which could be trimmed or structured. The key create_project-specific guidance is front-loaded, but the latter half reads more like general platform documentation than focused tool usage.

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 22-parameter tool with no output schema and minimal annotations, the description is remarkably thorough: it covers idempotency, plan limits, email templating, upload behavior, upgrade routing, and security warnings. The main gap is that it does not describe the successful return payload shape, aside from mentioning plan_limit and returning the existing record on idempotent re-runs.

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%, but the description still adds meaning far beyond the schema: strict changes idempotency behavior, email templates support specific tokens like {{project.name}} and {{count}}, footer_mode off is unavailable on free accounts, uploads_enabled must be set before accepting files, and file inputs use multipart POST. This materially helps an agent use the parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Use to add one website under an existing client_id.' It also explicitly differentiates from a sibling by saying 'Prefer bootstrap_site when the client does not exist yet,' which is exactly the kind of sibling distinction an agent needs.

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 gives clear routing guidance: use this when a client already exists, prefer bootstrap_site when the client does not, and on plan_limit call create_upgrade_link and hand the Stripe URL to the human. It also explains plan restrictions that determine when this tool can be used.

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

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

With annotations only saying readOnly=false and idempotent=false, the description carries most of the behavioral burden and handles it well by explaining that Stripe webhooks perform the plan change and that the tool returns a handoff URL. It could go slightly further on whether each call creates a new Stripe session, but the key side-effect boundary is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core use case and return type are front-loaded, but the description becomes long with plan-by-plan feature lists, pricing, retention details, and feature exclusions. Much of this content is useful, but it goes beyond what is strictly needed to invoke the tool correctly.

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, yet the description clearly states what is returned (Stripe Checkout URL or Customer Portal URL), the relevant product variants, and the authentication/token constraints. Given two optional parameters and several plan states, nothing needed to call the tool 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 the baseline is 3, but the description adds operational meaning beyond the schema: it ties product=expansion to yearly teams, explains the free-block context for the yearly product, and clarifies operator vs team-scoped token requirements for team_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's deliverable ('Returns a Stripe Checkout URL to hand the human') and the exact conditions that call for it. It also distinguishes the Customer Portal URL and expansion-pack variant, so the purpose is unambiguous even among sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: use when a free team is blocked by plan limits, omit product for existing yearly teams, and pass product=expansion to add capacity. It also tells the agent what not to do ('Do not change plan in the database') and how token scope affects team_id.

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

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

Even though annotations already mark the tool readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context: plan capacity details, what counts toward submission limits, expansion pack semantics, retention rules, and brand mode values. It also discloses token authorization behavior, which goes beyond what annotations 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?

The description is long but dense; every sentence carries decision-relevant information such as plan limits, token requirements, or alternative tool routing. It is appropriately front-loaded with the core purpose, though the plan-pricing detail could arguably be trimmed without losing core callability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must convey what the agent will receive or need to interpret. It covers plan semantics, usage counting, limits, expansion packs, retention, branding modes, token requirements, and sibling tool alternatives, making it complete for correct invocation and expectation-setting.

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 schema already documents team_id fully, including its format and the operator/team-scoped distinction, so baseline is 3. The description reinforces this by adding operational context about when team_id is required and when it may be omitted, which is helpful but largely redundant with the schema's parameter 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?

The description opens with a specific verb and resource: "read the team's plan, usage this month, limits, expansion_packs, retention_days, and branding." It clearly distinguishes itself from sibling list tools by explicitly saying "Do not use this to list projects — call list_projects," and it routes to create_upgrade_link for upgrade actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use and when-not-to-use guidance: it names create_upgrade_link as the alternative for Stripe Checkout operations, and it states that list_projects should be used instead of this tool for project listing. It also gives concrete token-scoping rules, telling operator tokens to pass team_id and team-scoped tokens to omit it.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds only the singular-object scope and the exclusion about listing sites; it does not describe return shape or error behavior, but with annotations present this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The core action is front-loaded, and the important exclusion/alternative is immediately stated.

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?

The tool is simple: one required parameter, fully documented by the schema, with read-only and idempotent annotations. The description supplies essential cross-tool guidance. Nothing needed to call this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage for the single parameter, including UUID format and provenance ('Client id from list_clients or create_client.'). The description only references client_id in the routing note and adds no meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'inspect one client.' It clearly distinguishes itself from list_projects by saying it should not be used to list a client's sites, and the singular 'one client' implies contrast with list_clients.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool ('Use to inspect one client') and provides a direct exclusion with the alternative tool and parameter: 'Do not use to list that client's sites — call list_projects with client_id.' This gives clear routing guidance.

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

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

Even though annotations already indicate readOnly and idempotent, the description adds important non-obvious behavior not derivable from annotations or schema: files_url is private and should not appear in public snippets, turnstile always inherits from the project, webhook_url_override is nullable with inheritance semantics, and only email.subject and email.intro can be overridden. This is rich, useful behavioral disclosure with no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then packs high-value details into a compact paragraph. Every sentence contributes distinct information: scope, privacy-sensitive fields, inheritance behavior, nullable webhook semantics, and the alternative tool. There is 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?

Given the simple single-parameter schema, no output schema, and read/idempotent annotations, the description compensates well by clarifying key response semantics (resolved vs inherited settings, turnstile inheritance, nullable webhook override) and by explicitly preventing misuse through get_snippet. An agent has enough context to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, form_id, is already fully documented in the schema (100% coverage) with a clear source hint ('Form id from list_forms, create_form, or bootstrap_site'). The description does not need to add parameter syntax and does not repeat it, which is appropriate; the baseline of 3 applies because the schema carries the burden.

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 operation: 'read a form plus resolved and inherited settings,' and then clarifies its boundaries by saying 'Do not use to generate embed code — call get_snippet.' This distinguishes the tool from at least one sibling (get_snippet) and conveys exactly what resource and behavior is involved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly frames when to use the tool ('Use to read a form...') and when not to use it ('Do not use to generate embed code — call get_snippet'). It also names the alternative tool directly, giving the agent a clear routing decision without needing to inspect other definitions.

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

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

Even though annotations already declare readOnlyHint and idempotentHint, the description adds valuable behavioral context: 'Secrets are never returned', 'Returns stored values plus resolved.email', and clarifies how plan limits and usage counts behave. This goes well beyond the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and return values, and the alternative-tool guidance is useful. However, it is quite lengthy due to detailed plan/pricing explanations that go beyond what is needed to select or invoke the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description adequately covers what the tool returns, what it never returns, and the meaning of plan/usage values an agent may encounter. The single parameter is fully specified in the schema, and the read-only/idempotent behavior is reinforced by annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter project_id is fully described in the schema (format UUID, source from list_projects/create_project/bootstrap_site), so schema coverage is 100%. The description does not add parameter-level detail, but none is needed given the complete schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: 'inspect one website's settings' and enumerates the exact fields returned. It also distinguishes itself from siblings by explicitly saying 'Do not use to list forms — call list_forms', making the scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states clearly when to use the tool ('Use to inspect one website's settings') and names an alternative for a different need ('Do not use to list forms — call list_forms'). It also routes upgrade-related needs to create_upgrade_link, giving concrete when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds substantial behavioral context beyond those: it returns generated code containing the submit endpoint, does not require inventing a URL, has single-value snippet limitations, and requires manual handling of multi-value fields. This meaningfully supplements the annotations without contradicting them.

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 long but every sentence carries actionable information, and the core purpose is front-loaded. It could be improved by breaking the caveats into clearer sections, but there is minimal filler or repetition.

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 absence of an output schema, the description does an excellent job explaining what the snippet contains, how to handle multi-value fields, file uploads, success UI, and a security caveat about the inbox URL. An agent has enough context to call the tool and use the result 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%, with form_id and framework already described. The description adds context about 'Use after the form exists' and the resulting endpoint, but it does not substantially reinterpret the two parameters. The framework enum values are already explained in the schema, so the description adds only marginal parameter-level 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?

The description opens with a specific verb and resource: 'get copy-paste html, astro, or next code that posts to /s/:publicKey.' It clearly distinguishes this tool from get_form, get_submission, and other sibling getters by focusing on snippet generation rather than retrieving stored records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states a clear precondition ('Use after the form exists') and gives detailed guidance about how the returned snippet should be used, including when to use brackets, multipart POST, and redirect/success UI. It does not explicitly contrast with alternatives, but no direct sibling alternative exists, and the usage context is concrete and unambiguous.

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

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

With readOnlyHint and idempotentHint already present, the description adds valuable behavioral context beyond annotations: it clarifies the response includes files_url and that URLs should not be expected to be signed bucket URLs. This prevents a common failure mode.

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 deliver purpose, exclusions, and a critical caveat without any filler. The main intent is front-loaded and each 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 read operation with safety annotations, the description provides enough context to invoke the tool correctly and understand the return characteristics. No output schema is needed because the description states the important return components.

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 input schema fully documents submission_id, including format, pattern, and source. The description does not need to add much parameter detail, so the baseline of 3 applies given 100% 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 clearly states the tool reads one stored submission by id and specifies what it includes (file metadata and files_url). This distinguishes it from list_submissions and from the live submit endpoint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says not to use this for live submit tests and directs the agent to POST to /s/:publicKey instead. It also provides guidance on how to handle returned URLs by downloading from the inbox.

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

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

Annotations already declare the tool read-only and idempotent, so the safety profile is covered. The description adds meaningful behavioral detail beyond the schema: operator tokens must pass team_id, team-scoped tokens cannot target another workspace, and archived clients are hidden unless status is set to 'all' or 'archived'. This adds useful context without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, all information-dense, with the core purpose front-loaded and the exclusionary guidance placed efficiently. There is no filler or repeated schema content; 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 tool has no output schema and four parameters, the description covers the essential operational context: what the resource is, which sibling to use instead, token-based team_id requirements, and archive filtering behavior. This is complete enough for an agent to call the tool correctly in most situations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description goes further by clarifying the nuanced semantics of team_id for different token types and explaining the practical consequence of the status default. This adds value beyond what the parameter descriptions already state.

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-resource pair ('browse clients') and explicitly identifies clients as companies, removing ambiguity about the resource type. It also names a sibling tool (list_projects) and differentiates this tool by saying it is not for listing websites, which makes the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance and a clear exclusion: 'Do not use to list websites — call list_projects with client_id.' It also provides contextual usage rules for token scoping, explaining when team_id is required and when it may be omit, plus the archive-filter behavior. This is strong routing guidance with no reliance on inference.

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

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

Annotations already mark the tool as read-only and idempotent, so the bar is lower. The description adds valuable behavior beyond annotations: token-type requirements, workspace targeting restrictions, and team inference when client_id is passed.

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 sentences with no waste: it front-loads the action, explains parameter selection, covers token behavior, and routes to the correct alternative. 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 list tool with no output schema, the description covers all calling contexts, auth modes, and the key sibling distinction. It does not describe the response shape, but pagination parameters are already documented in the schema and the main invocation guidance is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful selection logic beyond the schema by tying project_id, client_id, and team_id to specific auth contexts and scoping rules.

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 an explicit verb and resource: 'Use to list forms.' It also distinguishes itself from the sibling get_form with 'Do not use to read resolved inheritance — call get_form,' making the scope clear.

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 gives explicit when-to-use guidance by parameter: pass project_id for one website, client_id for one company, or team_id for operator tokens. It also states exclusions and names the alternative, get_form, for inheritance reads.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful behavior beyond those annotations: archived projects are hidden unless status=all or archived, team inference happens when client_id is passed, and team-scoped tokens cannot target another workspace.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four compact sentences carry purpose, exclusions, token rules, and archive filtering without wasted words. The primary use is front-loaded and every sentence adds a distinct operational rule.

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 five-parameter list tool with no output schema, the description is complete enough: it covers purpose, parameter selection, token scoping, archive default, and the alternative tool. Pagination mechanics are already covered by the cursor and limit schema descriptions.

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 by explaining the relationship between client_id and team_id, the token-type requirements, and the status default behavior. This goes beyond the schema's field-level descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists projects/sites for browsing and explicitly contrasts itself with get_project for reading a single project's settings. This distinguishes it from a sibling tool without requiring the agent to open schemas.

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 gives concrete guidance: pass client_id for one client's sites, use team_id from list_teams for operator tokens, and let team-scoped tokens omit team_id. It also states an explicit when-not: 'Do not use to read one project's settings — call get_project.'

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

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

Beyond the readOnly/idempotent annotations, it discloses important behavior: data retention/pruning periods (30 days free, 730 days yearly), team inference from project_id/form_id, and workspace-scoping restrictions for team-scoped tokens. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the core purpose, and every sentence contributes decision-relevant information: plan availability, token scoping, retention, and the single-submission alternative. 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?

It covers purpose, auth/scoping, retention, and alternative routing, which is strong for a list tool with no output schema. The only gap is that it does not describe the return shape, default ordering, or default page size beyond what the schema hints through cursor and limit.

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?

Even though schema coverage is 100%, the description adds cross-parameter meaning: project_id or form_id can infer the team, and team_id from list_teams is only required for Operator tokens/OAuth when no scoping parameter is provided. This is meaningful semantic context beyond the schema field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Use to inspect recent posts,' a clear verb+resource statement, reinforced by the name and title 'List submissions.' It explicitly distinguishes itself from get_submission with 'Do not use to read a single submission — call get_submission.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when not to use the tool and names the alternative: get_submission. It also gives actionable token-scoping guidance, telling Operator tokens when team_id is required and team-scoped tokens when it may be omitted.

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

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

Annotations already indicate readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context: team-scoped tokens get one team, while operator/OAuth tokens get all belonging teams, and it mentions the one-team limitation for free accounts. It does not describe response shape, but that is not required for a read-only list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and remains compact. The sentence about creating another workspace is slightly tangential to listing teams, but it provides relevant context about why the returned team set may be limited. Overall, no word 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 zero-parameter, read-only, idempotent tool, the description is complete: it explains token-based visibility, points to the correct sibling for clients, and even notes team_id usage for downstream calls. There is no output schema, so lack of return-value detail is not a 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?

The tool has zero parameters and an empty input schema, so schema coverage is trivially 100%. No parameter documentation is needed; the description correctly focuses on behavior and output semantics instead.

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 action ('see workspaces this token can act on') and resource ('teams'), and explicitly differentiates from list_clients in the final sentence. It clarifies token-dependent scope, leaving no ambiguity about what the tool returns.

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 gives explicit when-to-use guidance based on token type, and directly names list_clients as the alternative for listing clients. It also notes workspace creation is dashboard-only, which helps an agent avoid attempting an unsupported action.

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

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

The description clearly discloses the destructive consequence—every previously shared inbox link stops working immediately—and provides recovery guidance by noting that get_project returns the new files_url. This goes beyond the destructiveHint annotation by explaining exactly what is destroyed and how to obtain the replacement.

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 compact and front-loaded with the triggering condition, followed by the key behavioral fact and the recovery path. Every sentence contributes essential information with 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?

For a single-parameter tool with a well-documented schema, clear annotations, and a description that covers the purpose, behavior, and post-condition, the context is complete. An agent has everything it needs to invoke the tool correctly and understand the impact.

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 input schema already fully documents project_id with a description and format restriction, so the description does not need to add parameter-level detail. The schema carries the semantic load here, and the description adds no parameter information, matching the baseline for complete 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 specifies a concrete action—rotating a project's private inbox URL—and clearly distinguishes it from generic updates by explaining the exact effect: issuing a new inbox key and invalidating previously shared links. This makes the tool's purpose immediately identifiable and distinct from siblings like update_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?

The description explicitly states when to use the tool: when a project's private inbox URL may have leaked. It does not name alternative tools or explicitly state when not to use it, but the use case is clear and specific enough for an agent to select it appropriately.

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

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

Annotations only say the operation is not read-only and not idempotent. The description adds meaningful behavior beyond that: the event is signed, the tool fails if no webhook URL and secret are configured, and it is available on free and yearly plans. This gives useful operational context without needing to list every side effect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, each carrying distinct information: the action, plan availability, an exclusion, and a failure condition. The most important action 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?

For a simple single-parameter tool, the description covers the action, the precondition for failure, and an alternative. It does not describe the success response, but the absence of an output schema and the simplicity of the operation keep this from being a significant 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?

There is only one parameter, project_id, and the schema already fully documents it with a clear description referencing where the id comes from. The tool description does not need to add parameter detail, so the high schema coverage sets a baseline of 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?

The description uses a specific verb and resource: 'POST a signed webhook.test event to the project's webhook URL.' It also clearly distinguishes itself from webhook-delivery inspection, so an agent can tell this tool apart from related 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?

The description explicitly states when to use the tool ('Use to POST...') and when not to use it ('Do not use this to inspect past deliveries — that is REST GET...'). It also notes the failure precondition, which helps the agent decide if this tool is appropriate.

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

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

Discloses important runtime behaviors: ignored writes for free accounts, plan-dependent allowed modes, and operator/team-scoped token requirements. The annotation layer only provides readOnlyHint=false and idempotentHint=true, so this description carries genuine extra weight; minor detraction for referencing email.footer_mode, which is not part of the input schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The first sentence front-loads the purpose and later sentences cover restrictions and alternatives. However, roughly half the text is plan-pricing and feature detail (e.g., submissions/month, retention, webhooks, Turnstile) that is not needed to invoke this tool, making it longer than ideal.

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 the nested branding semantics, plan constraints, auth requirements, limits on what can be changed, and explicitly routes plan changes to a sibling tool. Even without an output schema, an agent has enough to call update_account 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 description still adds meaning: name means rename, branding.mode is gated by plan, agency supports name/link/logo, and team_id is required for operator tokens. It goes beyond the field descriptions without replacing them.

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 exact operations: rename workspace or set branding, with account as the resource. It also includes an explicit negative directive — 'Do not use this to change the plan — call create_upgrade_link' — which differentiates it from the upgrade 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?

Names the alternative tool (create_upgrade_link) and the conditions for using it, including expansion packs. It also specifies token-based rules for when team_id is required versus optional, so the agent knows exactly when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, indicating a mutating but idempotent operation. The description adds scope context by narrowing the tool to rename-only, but does not disclose additional behavioral details such as side effects or response behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences deliver the core purpose and the key exclusion with no filler. The primary function is front-loaded, and the alternative tool is mentioned 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 simple rename operation with full schema coverage and helpful annotations, the description is complete enough for correct invocation. It does not describe return values, but no output schema exists and the operation is straightforward.

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 both client_id and name. The description's 'rename' wording loosely maps to the name parameter but adds no new parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('rename a client') and distinguishes itself from update_project by listing what it is not for. An agent can tell exactly what update_client does without needing to inspect 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 says when not to use the tool (for domains, Turnstile, or webhooks) and names the alternative tool, update_project. This gives the agent clear routing guidance and prevents misuse.

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

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

The description discloses many behavioral details beyond annotations: null overrides re-inherit project values, missing template fields render empty and never error, checkbox groups require [] suffixes or only the last value is stored, and file downloads live under a form-slug folder at files_url. These details align with idempotentHint=true and readOnlyHint=false, so no contradiction 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?

The description is long but every sentence carries operational value, and the purpose statement is front-loaded before the caveats. It avoids restating schema metadata and packs only the failure-prone details (HTML vs JSON array encoding, multipart uploads, template fallbacks) into a dense but non-redundant block.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter nested-object tool with no output schema, the description covers the critical semantic ground: override inheritance, token interpolation, multi-value field encoding, upload prerequisites, and public URL cautions. The remaining parameter details are all present in the 100%-covered schema, so an agent has everything needed to call update_form 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?

Although schema coverage is already 100%, the description adds significant meaning: email token syntax with {{project.name}} and {{count}}, fallback syntax {{name | "New submission"}}, webhook_url_override behavior, field_contract.name [] rules, and JSON vs formData distinction. This is precisely the kind of value beyond the schema that helps an agent pick correct parameter values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Use to patch form overrides,' which immediately distinguishes it from broader project tools like update_project. It further clarifies scope by stating what stays on the project (from_name, footer_mode, include_meta) and explicitly excludes Turnstile key changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('patch form overrides'), alternative routing ('Do not use this to change Turnstile keys — those live on the project'), and prerequisites ('Enable uploads on the project first'). The from_name/footer_mode/include_meta note signals when update_project is the right sibling instead.

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

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

Annotations only state readOnlyHint=false and idempotentHint=true, so the description carries the full burden of behavioral disclosure. It adds multiple non-obvious side effects: 'Updating project keys changes resolved settings on existing forms unless a form override is set,' 'Null Turnstile or webhook fields clear them,' and 'Missing fields render empty and never error.' It also warns against passing HTML, cautions that the files_url folder 'never put that URL in a public snippet,' and explains plan-based enforcement. There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph with several topical digressions—plan pricing, multipart POST file behavior, and inbox folder URLs—that are not strictly needed to invoke update_project. It is front-loaded with the core purpose, but later sentences drift into product-level behavior; a more structured layout with section breaks would make the guidance significantly easier to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 21 parameters, nested objects, plan restrictions, and no output schema, the description is remarkably comprehensive: it covers prerequisites, side effects, plan capacity rules, template token semantics, and a security warning. The only notable gap is the absence of explicit return-value or authorization information, but the surrounding context gives an agent enough to call the tool 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%, so the baseline is 3; the description lifts it by explaining nested email field structure, the template token language including fallbacks like '{{name | "New submission"}},' inheritance of upload settings ('forms inherit them'), and plan-restricted branding behavior not fully captured in the schema. It does not enumerate every property, but the schema already documents each, so the added semantics are meaningful rather than redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Use to patch website settings,' a specific verb and object that clearly identifies this as a mutation targeting project-level configuration. It further delineates scope with 'Do not use this to create forms' and explains that project keys affect existing forms unless overridden. However, it never explicitly contrasts itself with the sibling update_form, leaving the closest alternative differentiation implicit.

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 gives explicit routing guidance: 'Use create_upgrade_link to hand a human a Stripe Checkout (or Customer Portal) URL' and warns 'Do not use this to create forms.' It also provides prerequisites such as 'Enable uploads on the project first' and plan-eligibility constraints like branding.mode being 'ignored on free except furrow.' It does not name update_form as the alternative for form-level overrides, though it notes project keys change resolved settings unless an override is set.

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

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

The annotations only indicate readOnly=false and idempotentHint=true. The description adds meaningful behavioral context about authentication scoping: operator tokens must pass team_id, while team-scoped tokens may omit it and cannot target another workspace. This goes beyond what the annotations 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?

The description is compact and front-loaded with the primary purpose, then delivers token constraints and exclusions in efficient sentences. Every sentence adds necessary guidance; there is 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 two-parameter mutation tool with no output schema, the description is complete enough for correct selection and invocation. It covers the action, token behavior, required parameter provenance, and explicitly rules out adjacent use cases.

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 extra semantics for team_id by clarifying operator-token requirements and the 'cannot target another workspace' restriction for team-scoped tokens, which is not fully captured in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Use to rename a team.' It then explicitly distinguishes itself from creating a workspace, changing account-level settings, and changing clients/projects, so an agent can differentiate it from siblings like update_account, update_client, and update_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?

The description gives explicit when-to-use and when-not-to-use guidance. It names get_account/update_account as the correct tools for plan, usage, retention, and branding, and warns against using this tool to create workspaces or change clients/projects. It also explains token-specific requirements for team_id.

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

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

Beyond the annotations, the description reveals important side effects: a signing secret is generated only once if absent, and forms inherit it unless webhook_url_override is set. These behaviors are not visible in the schema description and help predict the call's consequences. It does not contradict the readOnlyHint=false or idempotentHint=true 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 three tight sentences, with the core purpose front-loaded and the exclusion placed immediately after. Every sentence contributes either to correct invocation, plan eligibility, or behavioral context. No filler or 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 3-parameter tool with a fully documented schema, the description covers what the tool does, when to use it, the main alternative, plan availability, and a non-obvious side effect. The schema already documents the parameters, so the description is complete enough for correct tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning around webhook_secret by explaining auto-generation and form inheritance, which helps an agent decide whether to omit or provide that parameter. It does not fully explain every edge case, such as rotating an existing secret, but it adds value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'set or replace the project webhook URL.' It also explicitly contrasts the tool with test_webhook, so an agent can distinguish it from the most relevant sibling without inspecting schemas.

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 a direct 'Use to...' instruction, states the plan availability, and provides an explicit exclusion: 'Do not use this for a one-off delivery — call test_webhook.' This is concrete when-to-use and when-not-to-use guidance.

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