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?

Beyond readOnlyHint=false and idempotentHint=true, it discloses that idempotency is keyed on client/project/form slugs, that notify_emails has no default and an empty value means nobody is emailed, that free accounts hit a hard active-project ceiling with a plan_limit error, and that missing template fields render empty rather than erroring. These are exactly the mutation-side behaviors an agent cannot infer from 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 purpose, pre-call checklist, and the update_form exclusion are correctly front-loaded, but the middle is a dense wall of pricing tiers, expansion-pack pricing, and general HTML/JS integration advice for services[] that is tangential to invoking this tool. It earns much of its length given 27 parameters, but specific dollar figures and Object.fromEntries warnings could be trimmed.

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 27-parameter nested mutation tool with no output schema, it covers prerequisites, plan constraints, error routing, and the update_form alternative thoroughly. It is slightly short on what a successful call returns (ids, generated webhook_secret), though the schema notes the secret is generated and returned when omitted.

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 schema already carries the baseline, but the description adds real meaning: name/slug are the client while project_name/project_slug default to the same values, team_id requirements differ by token type, and the [] suffix convention for multi-value fields must be mirrored on field_contract.name. Some of that guidance is scattered mid-paragraph rather than attached to clear parameter groups.

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

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

The first sentence names a specific composite verb+resource set: stand up a client, one website (project), and its forms in a single call. That immediately differentiates it from the granular siblings create_client, create_project, and create_form, which each do only one of those things.

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-not guidance ("Do not use when you only need to patch an existing form — call update_form") and routes the plan_limit failure to create_upgrade_link. It also states the pre-call questions to ask the human and the operator-token vs team-scoped-token rules 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?

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?

The description reinforces the idempotentHint with concrete semantics ('Idempotent on slug unless strict is true') and discloses inheritance behavior — omitting overrides inherits project notify emails, webhook, redirect, require_turnstile, and email templates. It also surfaces a real prerequisite ('Enable uploads on the project first') and a warning not to expose files_url publicly. Much of the override mechanics are also in the schema, so it isn't fully additive.

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

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

Purpose and idempotency are correctly front-loaded, but a large block is devoted to client-side HTML/JS integration (bracket suffixes, fetch arrays, multipart, files_url) that is tangential to *creating* a form. The density is high and several sentences about the download inbox sit far from the tool's core action.

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 14-parameter tool with nested objects and no output schema, the description covers the essentials: prerequisites, inheritance/null semantics, field contract conventions, and what happens on slug collision ('returning the existing record'). It stops short of clarifying the return payload shape, but the idempotency note hints at it.

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

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

Schema coverage is 100%, so the schema already carries per-parameter meaning, making 3 the baseline. The description adds cross-cutting semantics that a single field description cannot convey: the omit-to-inherit rule for all overrides, the [] name-suffix convention shared across field_contract and HTML, and the JSON/array guidance (formData.getAll, no Object.fromEntries).

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

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

Opens with a specific verb + resource + scope: 'Use to add a form under an existing project_id.' That clearly distinguishes it from update_form/archive_form in the sibling set. It stops short of naming a sibling explicitly, but the create action 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?

'Use to add a form under an existing project_id' gives a clear precondition (an existing project) and the idempotency clause ('Idempotent on slug unless strict is true') tells the agent how re-runs behave. No explicit when-not guidance or named alternative for editing an existing form, so it falls short of a 5.

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

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

Beyond the idempotent annotation, the description explains idempotency on slug unless strict is true, free-account project limits, plan_limit behavior, footer_mode constraints on free accounts, and that uploads must be enabled before file inputs work. It also discloses template rendering behavior and warns not to put the project inbox 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 purpose and idempotency behavior are front-loaded, but the description then expands into pricing tiers, expansion packs, monthly submission capacity, retention periods, and MCP/webhook availability. Much of that is product documentation rather than guidance needed to create a project, so the definition is substantially bloated.

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 25-parameter tool with a nested email object and no output schema, the description covers the important invocation context: client existence, idempotency, plan-limit handling, email token behavior, and upload prerequisites. It does not describe the normal return shape beyond special cases like plan_limit and generated webhook_secret, which is the main remaining 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 the baseline is 3, but the description adds meaningful semantics for the optional email object, token interpolation and fallback syntax, footer_mode limitations, and enabling uploads. It still leaves many of the 25 parameters to the schema, which is reasonable given the full 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 opening sentence states a specific verb and resource: add one website under an existing client_id. It also distinguishes itself from bootstrap_site for the case where the client does not yet exist, so an agent can tell the two apart 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 description explicitly says when to prefer bootstrap_site and what to do when create_project returns plan_limit by routing to create_upgrade_link. These are concrete alternatives and error-routing instructions, not merely implied usage.

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?

Adds real context beyond the annotations: the tool produces a URL for a human rather than mutating plan state, webhooks own the DB write, and operator tokens must pass team_id while team-scoped tokens cannot target another workspace. It does not address repeat invocation (idempotentHint=false implies a new Checkout session each call) or link expiry, which are the remaining behavioral gaps.

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

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

Front-loads the trigger well, but roughly a third of the text is duplicated: the plan limits are stated once as trigger conditions and again as a 'Free:' / 'Yearly:' spec sheet, and 'Use create_upgrade_link to hand a human a Stripe Checkout (or Customer Portal) URL' restates the opening. Pricing tier detail crowds out the actionable call instructions.

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 tool with no output schema, everything needed is present: when to call, what URL comes back, token scoping, the webhook ownership of plan state, and the error surface ('other values return plan_limit'). No essential invocation detail is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining the semantics the enum alone cannot convey — omitting product on a yearly team yields a Customer Portal URL, while product=expansion adds a $99/year 5,000-submission pack. The team_id guidance (operator token vs team-scoped token) also reinforces the schema note.

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 (create an upgrade/billing link) and immediately names the artifact it returns: a Stripe Checkout URL (or Customer Portal URL). No sibling tool touches billing, and the description makes the billing/plan boundaries 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?

Gives explicit triggering conditions ('when a free team is blocked on the 3-project, 100-submission, or one-workspace limit'), an explicit branch (already yearly → omit product for a Portal URL), and an explicit prohibition ('Do not change plan in the database — Stripe webhooks do that').

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 establish readOnly and idempotent, so the description wisely focuses on what annotations cannot express: secrets are never returned (TypeSafe key, Twilio Auth Token), plan-capped fields return plan_limit, and error/limit behavior per plan tier. That is genuine added context; the remaining plan pricing detail is domain lore rather than 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?

Front-loaded correctly with purpose and exclusions, but the middle is a wall of plan-tier minutiae ($199/year, $99/year packs, 730-day retention, branding mode values) that an agent only needs occasionally. Several sentences could be condensed without losing call-correctness.

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

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

No output schema exists, and the description compensates by enumerating return fields down to nested paths (ai.typesafe_key_set, sms.configured) plus authentication constraints. What's missing is a sense of response shape/structure and whether usage figures are cumulative or period-bounded.

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 covers it at 100%, so the baseline is 3. The description earns above-baseline by explaining the conditional requirement of team_id — mandatory for operator tokens/OAuth, optional for team-scoped frw_ tokens, and never usable to 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?

Opens with a specific verb and resource ('Use to read the team's plan, usage this month, limits...') and enumerates the exact fields returned, so an agent knows precisely what it gets. It distinguishes itself from the closest lookalike by name ('Do not use this to list projects — call list_projects'), though the dense mid-sentence field paths slightly blur the headline 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?

Explicitly routes two adjacent tasks away: create_upgrade_link for Stripe Checkout/Customer Portal, and list_projects for project listings. It also gives token-scoping rules (operator tokens must pass team_id from list_teams; team-scoped tokens may omit it). It stops short of stating when an agent should prefer this over, say, get_client or get_form, but those are clearly different resources.

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?

Annotations already declare readOnlyHint and idempotentHint, so safety is covered; the description adds real value beyond that by stating that stored values are returned alongside resolved.email, that secrets are never returned, and that plan values are capacity rather than a feature ladder. It omits anything about response shape or error behavior, but the security and semantic caveats are meaningful additions.

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

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

The core purpose and the sibling exclusion are correctly front-loaded, but roughly half the text is a pricing tier catalogue ($199/year, $99 expansion packs, free-tier quotas) that belongs to the billing/upgrade tools rather than to a read tool. The retention and plan_limit details justify some of it, yet the volume dilutes the actionable content.

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 tool with no output schema, the description covers what is returned, what is deliberately withheld (secrets), and why plan fields return plan_limit values. Only the lack of guidance on error cases or ordering keeps it from being fully 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?

With a single parameter at 100% schema description coverage, the schema already explains that project_id comes from list_projects, create_project, or bootstrap_site. The description adds nothing about format or edge cases for project_id, so the baseline 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?

Opens with a specific verb and resource ('inspect one website's settings') and enumerates the exact fields returned (domains, webhook URL, email templates, plan, usage, retention_days, branding). It also explicitly distinguishes itself from a sibling by ruling out list_forms, so an agent can route without reading either schema.

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

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

Gives a clear when-to-use (inspect a single site's config) plus an explicit when-not/alternative ('Do not use to list forms — call list_forms'), and redirects upgrade flows to create_upgrade_link. It does not distinguish from get_account or get_client, which the field list only implies, so it falls short of full alternative coverage.

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?

readOnlyHint=true and idempotentHint=true are consistent with a code-generation read. Beyond annotations it discloses real behavior: the returned submit_url must be hardcoded (not moved into .env/NEXT_PUBLIC_*), the public key is not a secret, files_url points at the project inbox and must never appear in a public snippet, and file inputs require multipart with uploads enabled. That is substantial context 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?

Front-loaded with purpose and the 'do not invent a submit URL' constraint, but the single dense paragraph packs in post-invocation integration rules (bracket suffixes, fetch arrays, multipart, inbox URLs, success UI, env-var policy) and repeats the [] suffix rule twice. For a two-parameter read tool this is over-stuffed and would benefit from splitting invocation-critical guidance from downstream implementation notes.

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

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

With no output schema, the description carries the burden of describing what comes back (html/astro/next snippet, submit_url, files_url) and the constraints on using it safely. Nothing an agent needs to call this correctly, or to avoid the common failure of inventing a submit URL, appears to be 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 the enum for framework is already documented in-schema as html/astro/next flavors. The description adds only a light constraint that form_id must reference an existing form ('after the form exists'); the long multi-value/file-input text describes the returned snippet, not the two input parameters. Baseline 3 is appropriate when the schema does the 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+resource: returns copy-paste html/astro/next code that posts to /s/:publicKey. That output is unlike anything any sibling produces (all siblings are CRUD on clients/forms/projects/submissions), so an agent can route to it without opening the schema. The first sentence also names the precondition 'after the form exists', which further pins what it does.

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 about when to use it ('Use after the form exists'), when to hand-write instead ('Snippets are single-value inputs; write checkbox groups and multi-selects yourself'), and prerequisites ('Enable uploads on the project first'). It also covers what to do after receiving the snippet (add success UI, don't leave visitors looking at JSON) and routes to furrow://docs/submit-success and furrow://docs/testing for depth.

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?

Goes well past the annotations: it discloses the authorization requirement (owner of both teams; team-scoped tokens cannot), what is preserved (public keys, snippets, inbox links, webhook secrets), and three concrete refusal conditions (slug collision, free-plan project cap, Twilio requirement for text alert numbers). The destructiveHint=false annotation is consistent with a move that preserves all identifiers, and the description supplies the human-confirmation step the annotation layer 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?

Front-loaded with the triggering condition, then invariants, auth, and refusals in a compact sequence with zero filler sentences. Slightly dense in the refusal clause ('when a free destination would pass 3 projects'), which reads tersely and could be clearer, but 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?

No output schema exists, and the description never says what a successful move returns or whether it is synchronous, which is the main remaining gap for an operation touching many resources. Auth, side effects, failure modes, and confirmation requirements are otherwise fully covered for a tool of this complexity.

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

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

Schema coverage is 100% and both the 'pass slug' hint and the 'you must own it' ownership note already appear in the schema property descriptions, so the description adds little parameter-level meaning. Baseline 3 is appropriate since the schema 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 ('move a client (company) and all its projects, forms, submissions, and files') and names the destination scope ('another workspace they own'). The final sentence explicitly disambiguates from the sibling operations archive_client and update_client ('Do not use this to rename or archive').

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 triggering condition ('Use when the human asks to move a client'), an explicit exclusion ('Do not use this to rename or archive'), and a procedural precondition ('Confirm the destination team name with the human first'). An agent knows when to select this tool and when to route elsewhere without reading any other definition.

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 readOnlyHint=false and idempotentHint=false; the description adds the important non-obvious behavior: it sends one real text per number, returns per-number Twilio errors, and 'success' only means Twilio accepted, not delivered, due to carrier filtering of unregistered US senders. It also points to a doc resource for error codes, which 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?

Front-loaded with the action and prerequisite, and every sentence contributes distinct information (preconditions, return shape, success semantics, doc pointer, sibling exclusion). It is slightly dense at five sentences, but nothing is 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?

No output schema exists, yet the description describes the return value (per-number results with Twilio errors) and the success caveat. With one 100%-covered parameter and explicit preconditions, an agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the single project_id parameter is already fully documented with a format and source tools (list_projects, create_project, bootstrap_site). The description only indirectly references the parameter via 'the project's numbers' and adds no new syntax or sourcing guidance, so the schema 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?

The description names a specific verb (send one test text), the exact resource (each of the project's numbers via the team's Twilio account), and explicitly distinguishes itself from the sibling test_webhook. An agent can tell what it 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?

It gives an explicit precondition ('Use after setting notify_phones'), failure conditions (no Twilio account, no notify_phones), and a named alternative with the exclusion ('Do not use this to test email or the webhook — call test_webhook'). This is the when/when-not/alternatives pattern at full strength.

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?

Goes well beyond readOnlyHint=false/idempotentHint=true: discloses that free plans return plan_limit for non-furrow branding, that spam never fires a webhook, that secrets are write-only, and that sms: null disconnects. Loses a point because the plan/capacity paragraph is padded and partially restates the branding constraint already stated earlier.

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

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

Front-loaded with concrete actions, which is good, but the plan-limit rule appears twice (once as 'Free accounts keep branding.mode and email.footer_mode at furrow' and again in the Free/Yearly tier breakdown), and the pricing paragraph is longer than the calling 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 5-parameter mutation tool with nested objects and no output schema, the description covers error paths (plan_limit), permission/token scoping, null semantics for every nested field, and where the plan lives instead. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds operational meaning — omit auth_token later to keep the saved one, null clears the TypeSafe key, notify_suspected_spam defaults true and affects both email and webhooks, and notify_phones live on the project not here.

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 and enumerates the exact resources it changes: workspace name, branding, AI spam filter, Twilio SMS. An agent can distinguish it from update_team and update_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?

Explicitly routes away from itself: 'Do not use this to change the plan — call create_upgrade_link,' and names list_teams as the source of team_id for operator tokens. It also names the escalation path (furrow://docs/text-alerts, create_upgrade_link) for the human-facing cases.

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?

Beyond the readOnly=false and idempotent=true annotations, the description discloses meaningful behavior: null inheritance, [] meaning no Cc/Bcc or silenced texts, missing template fields rendering empty, and no HTML allowed. Some of the behavioral detail is about snippet and inbox usage rather than update_form itself, which keeps it from being 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?

It starts well with the override-patching purpose and null semantics, but then becomes an overlong mix of email templating, raw HTML field naming, fetch/multipart instructions, and public snippet warnings. Much of that does not help an agent invoke update_form and buries the relevant parameter guidance.

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

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

For a 12-parameter mutation with no output schema, the description covers the tricky inheritance and array semantics well. It omits return/confirmation behavior and does not mention several parameters such as name, redirect_url_override, and webhook_secret_override, but the schema documents those directly.

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 adds useful semantics for override parameters, especially null inheritance, [] behavior, template tokens, and the [] suffix convention for multi-value field_contract 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?

The description gives a specific verb and resource: patching form overrides. It also draws a clear boundary from project-level settings, but it never states that update_form can rename the form or change field_contract as a whole, so the stated purpose is narrower than the actual tool.

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 says when to use this tool and when not to, e.g. null re-inherits, Turnstile keys belong to the project, and SMS needs Twilio configured first. It does not name update_project as the alternative, but the operational boundary is easy to infer.

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 adds substantial behavior beyond the annotations: plan limits that return plan_limit, token rendering and fallback behavior, inheritance by forms, null-clearing semantics for Turnstile and webhook fields, and the side effect that updating project keys changes resolved settings on existing forms. These details materially help an agent predict the tool's effects.

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 very long and mixes update_project behavior with pricing details, create_upgrade_link usage, multipart submission instructions, download inbox warnings, and other tangential context. The purpose is front-loaded, but many sentences do not directly help an agent invoke this specific update tool.

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

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

For a 24-parameter nested update tool with annotations but no output schema, the description covers the most important behavior: plan constraints, inheritance, token rendering, null clearing, upload prerequisites, and the prohibition on using it to create forms. It is not perfectly focused, but it is complete enough 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?

Schema coverage is 100%, so the schema already carries most parameter semantics. The description still adds useful meaning beyond it, especially token syntax and fallbacks for email templates, inheritance rules for uploads and notification fields, and null-clearing behavior for some fields.

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

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

The description opens with 'Use to patch website settings,' giving a clear verb and resource, and it enumerates many project-level fields. It also says 'Do not use this to create forms,' which distinguishes it from creation siblings, though it does not explicitly contrast update_form or update_team.

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 some usage context, such as setting uploads and notification settings here because forms inherit them, and it explicitly warns against using the tool to create forms. However, it does not clearly say when to choose update_project over update_form or update_team, and the create_upgrade_link guidance is about a sibling tool rather than this one.

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

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

The 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.