Anvil MCP by usefulapi

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

Annotations only flag destructiveHint=true; the description supplies the crucial detail behind that flag — isDraft defaults to true and sends nothing, while isDraft=false with real signers SENDS signature-request emails. That is exactly the side-effect disclosure an agent needs before invoking a destructive tool, plus a test-mode escape hatch.

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, front-loaded with the purpose and then escalating to the two behavioral warnings. Nothing is padding — the mutation name, draft default, and test-mode tip all earn their place.

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

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

For an 8-parameter create tool with nested signer/file objects and no output schema, the description covers purpose, the main behavioral trap, and a dev-mode path. It omits what the call returns (e.g., a packet id/eid that would be needed to chain into anvil_generate_etch_sign_url or anvil_get_etch_packet), which is the one notable 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 description coverage is 100%, so the schema already documents all eight parameters, including isDraft's default and email behavior. The description reinforces the risky defaults with emphasis but adds little semantic detail beyond what the schema states, which is the expected baseline when 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 states a specific verb and resource — 'Create an Etch e-signature packet (documents + signers)' — and even names the underlying GraphQL mutation, so there is no ambiguity about what is created. It does not, however, explicitly differentiate itself from adjacent siblings such as anvil_get_etch_packet or anvil_generate_etch_sign_url.

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 real operational context: the default is a safe draft, and 'Use isTest=true while developing' tells the agent how to exercise the tool without side effects. It stops short of naming alternatives or stating preconditions (e.g., needing an existing organization/cast), so it is clear context without exclusions.

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 carry readOnlyHint, so the description's disclosure that identity comes 'from the API key' adds real auth context an agent needs. It also surfaces the underlying GraphQL query name, though it says nothing about failure modes (e.g. missing/invalid key).

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

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

Three tight clauses, front-loaded with the primary purpose, then the returned fields, then the usage hint. Nothing is padded or repeated from structured fields.

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

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

With no output schema, the description correctly carries the return shape (user plus orgs' eid/name/slug), which is enough to invoke and consume the result. It could mention error/empty behavior but is otherwise sufficient.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond confirming implicit API-key-based selection. Baseline 4 applies for a no-parameter tool.

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

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

States a specific verb and resource ('Get the authenticated Anvil user') plus the secondary payload (organizations with eid, name, slug). This clearly distinguishes it from sibling org-scoped tools like anvil_get_organization.

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?

'Good first call to discover org slugs/eids for other tools' gives explicit workflow context for when to reach for it. It stops short of naming a when-not condition or an alternative tool, but the positive guidance is concrete.

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 genuinely useful behavior beyond the annotations by disclosing the return payload shape ({ filename, byteLength, pdfBase64 }) and the REST endpoint, which matters since no output schema exists. However, it never explains the destructiveHint=true annotation or what 'destructive' means here, leaving that behavior undisclosed.

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

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

Three tight sentences with the core action front-loaded and the return contract following immediately. No filler, though the REST route adds marginal value for an agent that cannot act on it directly.

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 capably fills the gap by naming the returned fields, and the nested data object is documented. The remaining gap is the unexplained destructive annotation, which for a mutation-style tool should ideally be addressed in the description.

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

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

Schema description coverage is 100%, so all five parameters (including the nested data object) are already documented. The description's note that 'the data object's keys are the template's field aliases' largely restates the schema's own data description, adding little new syntax or format guidance. Baseline 3 applies.

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

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

States a specific verb and resource ('Fill an Anvil PDF template (cast)'), clarifies the input source and the return format. It does not, however, distinguish itself from the sibling anvil_generate_pdf, which an agent could reasonably confuse it with.

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

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

Usage is only implied: the parenthetical '(from anvil_get_cast)' hints at a prerequisite workflow step, but there is no explicit when-to-use guidance or contrast with anvil_generate_pdf/anvil_get_cast. An agent must infer the sequence.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the behavioral burden. It usefully discloses that the URL is one-time and that the GraphQL mutation is generateEtchSignURL returning { url }, partly explaining why the operation is flagged destructive, but it does not say what the URL invalidates, whether prior URLs are revoked, or any auth requirements.

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

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

Three short, front-loaded clauses: purpose and scope first, then use case, then the GraphQL mutation name and return shape. Every sentence earns its place with no filler.

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

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

With no output schema, the description compensates by stating the return value ({ url }), and the mutation name aids debugging. The two required params are fully covered by the schema, though the description does not note the fragility of a one-time link.

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

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

Schema description coverage is 100%, so both parameters (signer_eid, client_user_id) are already documented with their source and purpose. The description adds no parameter-level detail beyond the schema, which is the baseline-3 case.

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 ('Generate a one-time embedded signing URL') scoped to 'a specific signer in an Etch packet', which separates it from siblings like anvil_get_etch_packet and anvil_create_etch_packet. The parenthetical use case (iframe/redirect signing flows) further pins down the intent.

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

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

The parenthetical '(for iframe/redirect signing flows)' gives an implied context for use, but the description never states when to use this instead of getting the packet or creating one, nor any prerequisites. Usage is inferable rather than explicit.

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 carry only destructiveHint=true, so the description usefully adds the transport (POST /generate-pdf), the exact input shape per type, and the return structure ({ filename, byteLength, pdfBase64 }). It does not explain why the operation is flagged destructive, nor auth or size limits, but with annotation coverage the bar is lower and this adds real 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?

Front-loaded with purpose, then the REST mapping, the two input shapes, and the return contract — four dense statements with no filler. Slightly fragment-heavy, 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?

With no output schema, the description compensates by naming the return fields, and it covers both enum branches of the polymorphic input. Missing only secondary details such as error behavior or payload constraints, which are minor for a generation tool.

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

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

Schema description coverage is 100% and the schema already documents the polymorphic data field, type enum, and title. The description restates the same two data shapes almost verbatim, so it adds little meaning beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Generate a brand-new PDF from HTML or Markdown') and distinguishes itself from the sibling anvil_fill_pdf by emphasizing brand-new creation versus filling an existing document. An agent can select it without opening the schema.

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

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

The word 'brand-new' implies this is for creation rather than filling a template, but no alternative tool is named and no when-not guidance is given. Usage context is inferable rather than explicit, which is the definition of minimum-viable.

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

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

With only readOnlyHint=true in annotations and no output schema, the description carries the return-value burden and does so: it discloses that the response contains title, version number, and a template boolean. It also reveals the backing mechanism ('GraphQL query: cast'), which helps an agent reason about failure modes, though it says nothing about behavior for an invalid or missing eid.

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

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

Two compact sentences with the fetch semantics and return fields front-loaded, followed by the chaining instruction. Nothing is repeated from the schema or annotations, and every clause earns its place.

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

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

For a single-parameter read with no output schema, the description supplies the essentials: what is fetched, what comes back, and where the result is consumed next. It could be marginally more complete by noting error behavior for a nonexistent eid, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the single eid parameter, so the baseline is 3; the description goes slightly beyond by identifying the eid as the cast's identifier and, crucially, explaining that the returned eid is what feeds cast_eid on anvil_fill_pdf. No format or validation details for the eid itself are added.

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 (Fetch) and resource (a cast / Anvil PDF template) and disambiguates the term 'cast' for an agent unfamiliar with Anvil's vocabulary. It also previews the returned fields (title, version number, template flag), so it is distinguishable from sibling getters like anvil_get_weld or anvil_get_etch_packet.

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

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

Explicitly routes the agent forward: 'Use the returned eid as the cast_eid for anvil_fill_pdf,' naming the concrete sibling and parameter to chain into. It does not state when not to use this tool or contrast it with the other anvil_get_* siblings, so it stops short of full when/when-not guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is only to add context. It discloses the response contents (signers with routing order, status), which is useful, but says nothing about auth requirements, pagination, or error behavior for an unknown eid.

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

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

Two tight sentences, zero filler. The purpose and returned fields are front-loaded, with the 'when to use' and GraphQL query name trailing as secondary detail.

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

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

With no output schema, the description compensates well by enumerating the returned fields, and it names the GraphQL query. Minor gaps remain around failure modes or how signer status values should be interpreted.

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

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

Schema description coverage is 100% and the schema already explains that eid is the Etch packet eid returned by anvil_create_etch_packet. The description only restates 'by eid' with no additional format or constraint detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Fetch an Etch e-signature packet by eid') and enumerates the payload returned (status, details URL, document group, signers). It is clearly distinguishable from the sibling anvil_create_etch_packet, which the parameter description even cross-references.

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

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

Provides an explicit use case: 'Use this to check signature progress.' That is a clear triggering condition, but it names no alternative tool or when-not condition (e.g., versus anvil_generate_etch_sign_url for signing actions).

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 already establishes this as a safe read, so the description only needs to add context. It usefully discloses the return payload (templates and workflows) and the identifier requirement, but says nothing about size, pagination, or what happens if both eid and slug are supplied.

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

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

Three short sentences, front-loaded with purpose and return contents. The trailing 'GraphQL query: organization' is implementation detail that aids debugging but is not strictly necessary for tool selection.

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 returns and does so at a high level (casts and welds). Combined with a 100%-covered two-parameter schema and a read-only annotation, an agent has enough to call it correctly; only the return shape and pagination are underspecified.

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 would be 3, but the description adds real value the schema cannot express: 'at least one is required' captures the either/or constraint that the zero-required-parameter schema leaves ambiguous. The slug's provenance (from anvil_current_user) is left to the schema description.

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

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

States a specific verb and resource ('Fetch an Anvil organization') and adds what comes back (casts and welds), which is more than the title. It implicitly supersedes the narrower siblings anvil_get_cast and anvil_get_weld by returning both, but never names them, so the agent must infer the distinction.

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 only guidance given is identifier selection ('Provide either its slug or its eid'), which is invocation guidance rather than when-to-use guidance. There is no statement about when to prefer this over anvil_get_cast or anvil_current_user, so routing is left to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is reduced. It adds that the response includes forges with eid/name/slug, which is genuine return-shape context, but says nothing about auth requirements, error behavior when the eid is unknown, or payload size.

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

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

A single front-loaded sentence that packs in the resource, the jargon gloss, and the returned sub-fields without waste. Only the trailing GraphQL query name is arguably filler for an agent that never writes the query itself.

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 must carry the return-shape burden; it names forges and three of their fields but leaves the rest of the weld payload unspecified. The strong overlap with anvil_get_weld_data is never addressed, leaving a real selection ambiguity.

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

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

Schema description coverage is 100% with a single required parameter, so the baseline is 3. The description only restates that lookup is 'by eid' and adds no format, ID-prefix, or sourcing detail 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 ('Fetch a weld') and helpfully decodes Anvil jargon (weld = workflow, forges = form steps). It does not differentiate from the sibling anvil_get_weld_data, so an agent cannot tell from the text alone which of the two to call.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obviously adjacent sibling anvil_get_weld_data. The only routing aid is the trailing 'GraphQL query: weld' note, which is not a usage condition.

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 already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds genuine value by enumerating the record contents (completion state, test flag, creation time) and the backing GraphQL query, but says nothing about error behavior on a missing/invalid eid or any access constraints.

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

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

One tightly packed sentence: verb and scope first, the parenthetical definition immediately after the resource, then the return fields and the query name. No filler, nothing redundant, fully front-loaded.

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

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

With no output schema, the description usefully summarizes the returned fields, and it correctly frames the entity relative to the workflow. It is slightly incomplete in not covering failure modes or whether the field list is exhaustive, but for a single-parameter read this is close to sufficient.

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

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

Schema description coverage is 100% and there is a single required parameter, so the schema fully documents eid. The description only adds 'by eid', which is already visible in the schema; it contributes no format, validation, or lookup-semantics detail beyond that. Baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a weldData record), and crucially defines that resource as 'a single submission to a weld (workflow)', which separates it from the sibling anvil_get_weld (the weld itself). It also names the underlying GraphQL query, so an agent can identify the exact operation.

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 definition of 'weldData = a single submission to a weld' implicitly signals when this tool applies versus anvil_get_weld, but there is no explicit when-to-use statement, no alternative named, and no precondition guidance (e.g., what to do if the eid is unknown or belongs to a different entity type). Usage is inferable but not spelled out.

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