Fillo

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

Goes well beyond the annotations: it discloses that the HMAC signing secret is returned EXACTLY ONCE and must be stored immediately, that a human approver (not the agent) sees the secret, and that internal/loopback targets are refused. Annotations only mark it as non-readOnly, destructive and non-idempotent; the description supplies the operationally critical 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?

Purpose is front-loaded in the first clause and every sentence carries information, but the second sentence is grammatically awkward ('Respondent answers then leave Fillo for an endpoint Fillo does not control'), costing some readability.

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 an output schema present, return values need not be explained, and the description still covers the one-time secret, the approval flow, and the loopback refusal. It is nearly complete for a 4-parameter mutation tool; only explicit sibling routing is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the outbound credential (bearer or x-api-key) and the abandoned-events default, which mirrors the schema rather than adding new syntax or constraints.

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

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

Opens with a specific verb+resource: 'Add a signed webhook to a form.' The agent can distinguish this from sibling webhook tools (fillo_list_webhooks, fillo_update_webhook, fillo_remove_webhook) by the verb. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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

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

Provides context about the human-approval flow and the optional draft.abandoned events, which implies when the tool fits. However, it never states when to use this versus fillo_update_webhook or fillo_list_webhooks, nor any prerequisites, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation/safety profile is covered. The description adds real value beyond that: the anti-escalation rules, the last-owner demotion block, and the fact that ask-policy connections trigger a human approval link — operational behavior an agent cannot get from the annotations.

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

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

Two dense sentences with the core action front-loaded and constraints trailing. Every clause carries information, though the constraint list is packed tightly and could be slightly easier to parse.

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?

An output schema exists so return values need no explanation, and annotations cover the destructive/idempotency profile. The description supplies the permission and approval context a mutation tool needs; only the semantics of the role values remain unaddressed.

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

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

Schema coverage is 50%: 'member' is documented but 'role' has only an enum with no description. The description restates 'member id or email' (already in the schema) and does not explain the rank ordering of member/admin/owner or the default behavior, so it only marginally compensates.

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 (Set/change) and resource (a member's role), with the accepted identifier form (member id or email). It is clearly distinguishable from siblings like fillo_invite_member, fillo_remove_member, and fillo_revoke_agent 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?

The description implies usage through its constraints (anti-escalation, last-owner protection, human approval for ask-policy connections) but never states when to prefer this tool over inviting/removing a member or how it relates to fillo_list_members. 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 only cover the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds a genuinely important behavioral fact the annotations cannot convey: the plaintext is returned EXACTLY ONCE and must be captured immediately. It still omits auth/permission requirements and whether the token is scoped to anything beyond "stage-only".

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

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

Two sentences, zero waste, and the operation plus its one critical caveat are both front-loaded. Nothing redundant with the title or schema.

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?

An output schema exists, so return values need no explanation, and the one-shot plaintext behavior is the essential missing piece that the description supplies. Remaining gaps are minor: the optional `name` argument and any prerequisite/auth context for minting a deployment token.

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 0% and the single `name` parameter (optional, maxLength 80) is never mentioned in the description. "For a deployment" gestures vaguely at naming but gives no guidance on the identifier, so the description does not compensate for the coverage gap.

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 ("Mint"), a specific resource (fsync_ token), and a distinguishing scope constraint ("stage-only ... for a deployment"). An agent can separate this from fillo_list_sync_tokens and fillo_revoke_sync_token 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?

Usage is only implied: the description tells the agent what to do with the token after creation (hand it to the user or CI secret store), which situates the tool in a CI/deployment workflow, but it never states when to mint one, what prerequisites exist, or why one would choose this over the revoke/list siblings.

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 flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it names the exact destruction scope (form, every response, files), declares irreversibility, discloses the two-step single-use-approval flow, and warns that live embeds and the hosted URL break after approval. This is exactly the behavioral context the annotations cannot supply.

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

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

Two tight sentences, front-loaded with the destructive scope before the approval mechanics and side effects. No sentence is filler; each adds a distinct fact.

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

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

An output schema exists, so the approval-link return value need not be detailed further. Combined with the destruction scope, irreversibility, authorization requirement, and embed/URL side effects, the definition leaves nothing an agent needs missing.

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

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

Only one parameter and schema description coverage is 100% ('Form id, slug, or push handle'), so the schema carries the semantics. The description adds no format or identifier guidance beyond it, making the baseline 3 appropriate.

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

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

States a specific verb (delete) and resource (form) and immediately expands scope to 'every response, and their files', distinguishing it from siblings like fillo_delete_response and fillo_delete_respondent. An agent can tell exactly what is removed without opening the schema.

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

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

Gives clear operating context: the tool never runs directly and instead returns an approval link a workspace owner or admin must confirm, which tells the agent what to expect and who is authorized. It does not, however, name alternatives (e.g., unpublish_form to merely take a form offline), so the when-not-to-use case is left implicit.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, and the description goes well beyond that: it states the action is irreversible, that it always requires a human approval link before proceeding, and that the receipt arrives in an untrusted envelope echoing the external id from identify(). That is substantial operational context, especially the approval-gate and untrusted-input warning.

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 scope statement and the destructive/approval caveat are front-loaded, and every sentence carries an operational fact. It is dense with jargon ('untrusted envelope', 'identify() call') that is meaningful but slightly compression-heavy for a two-parameter 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?

An output schema exists, so return values need not be described, yet the description still explains the key response artifact (the approval link and the identity-echoing receipt). Combined with the destructive and irreversible warnings, an agent has everything needed to call this correctly and safely.

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

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

Schema coverage is 50%: 'respondent' is documented as profile id or external id, while alsoResponses has no schema description. The description compensates by spelling out that alsoResponses=true additionally deletes responses and files, which is the exact semantic the schema omits. It adds real value above the structured 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?

States a specific verb and resource (delete a respondent's profile/drafts, scrub identity from responses) and scopes it clearly against the closest siblings, fillo_delete_response and fillo_disable_identity. An agent can distinguish this GDPR-erasure tool from the plain response-deletion tool 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?

Names the governing use case (GDPR erasure) and the condition that expands scope (alsoResponses=true deletes responses and files too), which tells the agent when this tool is appropriate. It does not explicitly name alternatives such as fillo_delete_response for non-GDPR deletion, so the routing guidance is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, yet the description adds substantial context beyond them: uploaded files are erased too (cascade), the action is irreversible, and it returns a human approval link requiring owner/admin confirmation.

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

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

Two tightly written sentences that front-load the destructive scope before the approval-flow consequence, with no wasted words.

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

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

Even though an output schema exists, the description proactively explains the approval-link return and the full destructive footprint, so an agent has everything needed to call it correctly and set expectations.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema; the description adds no format or syntax detail beyond that, making the baseline 3 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?

Names a specific verb ('Permanently erase') and a precise resource ('one accepted response and its uploaded files'), which distinguishes it from siblings like fillo_delete_respondent and fillo_delete_form without needing to name them.

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

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

Usage is implied by 'one accepted response' (as opposed to held or other responses), but no explicit when-to-use guidance or alternatives (e.g. delete_respondent vs delete_response) are given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds value the annotations don't: the shape of the payload (state, failures, next retry, recent list) and the important caveat that counts only cover the retained window — a real constraint on interpreting results.

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

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

One sentence, front-loaded with the core payload description, with the retention caveat trailing. No filler, though the em-dash clause about the Activity page is more analogy than information.

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

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

An output schema exists, so return values need not be spelled out, and the description still previews the payload categories plus the retention scoping caveat. The main gap is the absence of any pointer to the retry/redeliver siblings for acting on unhealthy destinations.

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

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

Only one parameter, and schema coverage is 100% ('Form id, slug, or push handle' is documented in the schema). The description adds no format, default, or resolution-order detail beyond that, so the baseline of 3 applies.

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

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

States a specific resource and scope: per-destination delivery health (state, failures, next retry) plus a recent delivery list, anchored to the form's Activity page. This is clearly distinguishable from neighbors like fillo_response_summary or fillo_form_insights, though it never names an alternative directly.

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

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

Usage is implied by the Activity-page analogy rather than stated. There is no explicit 'use this when you need X, not Y' routing, and no mention of the obvious follow-up sibling fillo_retry_deliveries or fillo_redeliver_responses for taking action on failures.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, but the description adds real value beyond them: a guard condition (refused while forms require verified respondents) and the fact that a human approval link is always returned, implying this is gated rather than immediate. It stops short of explaining what the approval link entails or the effect on respondents.

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

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

Three short sentences, each carrying distinct information (action, precondition, return behavior), with no padding or repetition of the title.

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

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

With an output schema present, return values need not be described, and the description still flags the always-returned approval link. The main remaining gap is the approval workflow itself (who grants it, whether the secret is deleted immediately or after approval), which matters for a destructiveHint operation.

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 per the rubric the baseline is 4. There is nothing for the description to clarify on inputs, and it correctly does not invent any.

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 (disable identity verification by deleting the project identity secret), and the outcome is concrete rather than tautological. The enable/status siblings (fillo_enable_identity, fillo_identity_status) make the scope immediately clear without opening their 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?

Gives a genuine precondition: the call is refused while any form still requires verified respondents. However, it never names the alternatives (fillo_enable_identity, fillo_identity_status) or states when an agent should prefer to disable verification, so usage is inferred rather than guided.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description earns credit by disambiguating what 'destructive' means here: it stops only new deliveries and leaves the provider-side sheet, database, or channel intact, which a bare destructiveHint would not 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?

Two tight sentences with the core action front-loaded and the behavioral qualifier immediately after. Every clause earns its place and nothing is redundant.

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?

An output schema exists, so return values need not be described. The definition covers action and effect clearly; the only gap is routing guidance against the close siblings disconnect_integration and enable_integration, which the agent must reason out itself.

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

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

Schema coverage is 100%, with both parameters documented (including the provider enum), so the schema carries the load. The description adds no format, syntax, or value guidance beyond what the schema already provides; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Turn a form's destination off') and clarifies the scope of the effect. It implicitly contrasts with fillo_disconnect_integration by noting the provider-side resource 'is left in place', but never names that sibling, so differentiation is inferential rather than explicit.

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

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

The second sentence implies the use case (pause delivery without tearing down the destination), which nudges toward this tool over fillo_disconnect_integration. However, there is no explicit when-to-use, when-not-to-use, or named alternative, leaving the agent to infer the boundary.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful scope: destruction is limited to the staged draft, the live version is untouched, and respondents are unaffected — clarifying the blast radius of a destructive call.

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, action front-loaded, and the reassurance clause earns its place by delimiting the destructive scope. 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 annotations covering the safety profile and an output schema handling return values, the description is nearly complete for a single-parameter mutation. The only gap is the absence of explicit routing guidance versus sibling tools like fillo_unpublish_form.

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

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

Schema description coverage is 100% and the single 'form' parameter already documents its accepted forms (id, slug, or push handle). The description adds no syntax, format, or constraint detail beyond what the schema provides, 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 ('Drop') and resource ('a published form's staged draft') with the key scoping constraint that the live version stays intact. An agent can distinguish this from fillo_delete_form or fillo_unpublish_form by the 'keep the live version exactly as it is' clause, though no sibling is named explicitly.

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

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

Usage is implied rather than stated: the phrase 'keep the live version exactly as it is' signals this is the throw-away-the-draft path rather than publish. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. fillo_publish_form, fillo_unpublish_form), leaving the agent to infer routing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: the downstream effect (forms that send to it stop) and the fact that it always returns a human approval link, which is not derivable 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?

Three tight sentences, front-loaded with the action and its scope, then the side effect, then the reversibility/approval behavior. No filler and every sentence contributes distinct information.

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

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

For a destructive mutation with annotations and an output schema, the description covers impact, scope (project vs workspace), reversibility, and the approval-link return path, so an agent can call it confidently. Missing only explicit sibling routing, which is minor given the rich behavioral detail.

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

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

The single 'provider' parameter has 0% schema description coverage, so the description must carry the load. It does so by naming all four enum values (Notion, Slack, HubSpot, Discord), matching the schema enum exactly and making clear what each accepted value means.

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 ('Detach') and resource (the project's Notion/Slack/HubSpot/Discord account), and clarifies the scope is project-level rather than workspace-level. However, it never distinguishes itself from the similarly named sibling fillo_disable_integration or from fillo_remove_connection_account, leaving the agent to infer which of the near-synonyms to pick.

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

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

Usage is implied rather than stated: the line 'The workspace account stays available to other projects' hints at the contrast with a workspace-wide removal, but no explicit when-to-use or 'use X instead' guidance is given. Against siblings like fillo_disable_integration the agent must guess.

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

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

Annotations only mark this as a non-read-only, non-idempotent, non-destructive mutation, so the description adds real value: it discloses that unpublished edits are carried into the copy, that ownership is builder-owned, and that visibility is private until published. It does not mention permissions required or whether the source form is touched, which would complete the picture.

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

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

Two short sentences, zero filler, with the core action and its scope front-loaded ahead of the visibility caveat. 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?

An output schema exists, so return values need no explanation, and the description covers origin, content, ownership, and visibility well. It stops just short of the one operationally relevant detail an agent might need — whether the copy is immediately addressable or requires a subsequent publish step.

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% (both 'form' and 'name' are documented in the schema), so the schema carries the burden and a baseline 3 applies. The description adds no meaning beyond what the schema provides, such as how 'name' defaults if omitted.

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 ('Copy a form') plus the resulting artifact ('a new builder-owned draft') and scope ('into the same project'), so an agent knows exactly what the call produces. It does not name or distinguish itself from near-neighbors such as fillo_pull_form or fillo_get_library_form, which an agent might reasonably confuse with a copy 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?

No explicit when-to-use or when-not-to-use guidance and no alternatives named. The clause 'The copy is private until published' only implicitly suggests a follow-up with fillo_publish_form, leaving the agent to infer the workflow.

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 the annotations by disclosing the critical one-time behavior: the secret appears EXACTLY ONCE, an already-enabled project never re-reveals it, and ask-policy connections require human approval. These are high-value operational facts an agent must know before invoking a destructive, non-idempotent 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?

Two tightly written sentences with the action and its irreversible consequence front-loaded. Every clause carries distinct 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 zero-parameter tool with an output schema, the description supplies the essential context: what is produced, that it is shown only once, and how approval-policy connections are handled. 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?

There are zero parameters, so the baseline is 4. The description correctly adds no parameter detail because none exist, and the schema already covers the empty object shape.

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

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

States a precise verb and resource ('Mint the project identity secret') plus the downstream purpose ('so forms can require signed identify() calls'). This clearly separates it from fillo_disable_identity and fillo_identity_status without needing to open their 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 conveys the effect and a workflow detail (approval page, ask-policy approval link), which implies when the tool is appropriate. However, it never explicitly routes the agent between enable, disable, and identity_status, so usage guidance is inferred rather than stated.

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 flag destructiveHint=true and non-idempotent, and the description adds real behavioral context beyond them: the human approval link step, the 'no duplicate sheet/database' guarantee for Sheets/Notion, and provider-specific required keys. It doesn't clarify what is destroyed or the consequences of overwriting an existing config, so it falls short of 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?

Front-loads the action and the approval/idempotency caveats before the required config enumeration, and every clause earns its place given the nested-object burden. The dense comma-separated config list is long but justified.

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 three-parameter tool with an output schema, the description covers the activation flow, approval requirement, idempotency nuance, and complete config semantics for every provider — 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?

The schema describes 'config' only as 'Provider config (see the tool description)' with 100% top-level coverage but a fully opaque nested object, so the description carries the burden and delivers detailed per-provider key syntax for all five providers.

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

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

States a specific verb-plus-resource ('Turn on (or reconfigure) a form's ... destination') and enumerates all five supported providers, so an agent can immediately distinguish it from fillo_disable_integration and fillo_disconnect_integration.

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

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

Gives clear context for use (enabling/reconfiguring a destination, with the note that re-running on an already-on Sheets/Notion destination is safe) and implies the alternative disable path, but never explicitly names when NOT to use this tool or points to fillo_disable_integration/get_integration by name.

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 real behavioral traits: only accepted responses are counted, both responses:read and forms:read scopes are required, and the payload (verbatim respondent quotes) is untrusted. The auth requirement and security warning are exactly the kind of context annotations cannot carry.

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

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

Front-loads the highest-value information (what numbers come back), then filter mechanics, then auth/security caveats. Dense but every clause carries distinct information 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?

An output schema exists so return values need not be explained, yet the description still orients the agent well. Combined with annotations for the safety profile and explicit auth/scope and untrusted-payload notes, an agent has everything needed 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by grouping by/op/eq as an 'answer segment' and pointing to the fillo_list_responses filter grammar, which the schema does not convey (it only documents each param in isolation). This is useful added context over 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 names a specific resource (a form's responses) and enumerates the exact analytical outputs: totals, median completion time, week-over-week change, daily timeline, sources, drop-off funnel, and per-question distributions with CSAT/NPS. This lets an agent distinguish it from raw-list siblings like fillo_list_responses 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?

It connects the filter grammar to fillo_list_responses and notes the 'Accepted responses only' scope, implying when this analytics tool applies. However, it never explicitly states when to choose this over fillo_response_summary or fillo_list_responses, leaving the selection criteria to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description still adds value by spelling out the consequence (no subscribing/plan change/checkout) and by directing the agent to surface manageUrl for a human, which is behavioral guidance beyond the annotations.

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

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

Front-loaded with the payload contents, then the read-only constraint and the human handoff. The first sentence is a dense enumeration but every clause maps to an actual return field, so nothing is wasted; slightly long but efficient.

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?

An output schema exists, so return values need no further explanation, yet the description still names the key fields and the actionable manageUrl. Combined with annotations covering the safety profile, an agent has everything needed to call this 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly does not pad with fake parameter discussion.

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 (read) and enumerates exactly what is returned: plan tier and billing period, this month's response count against allowance, recent monthly usage, and the Settings link. This clearly distinguishes it from sibling read tools like fillo_get_settings and fillo_get_storage.

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 clear context and an explicit negative: 'an agent can never subscribe, change the plan, or open checkout — report the numbers and hand the human manageUrl.' That tells the agent what to do with the result and what it must not attempt, though it does not reference any sibling alternative by name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral value beyond that: the result reflects both the workspace preference and what forms actually render on its plan, flagging a plan-dependent outcome an agent would not otherwise know.

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 tight fragment with no padding, front-loading the resource and the plan-dependent nuance. It is slightly terse and grammatically a fragment rather than a complete sentence, but every word 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?

The tool has no parameters and an output schema, so the description need not explain return values or inputs. It covers the resource and the notable plan-dependent behavior; only routing guidance versus fillo_set_branding 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?

With zero parameters and vacuous 100% schema coverage, there is nothing for the description to clarify; baseline 4 applies. The description correctly omits parameter talk.

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 the specific resource (the workspace's badge preference) and adds scope about what forms render on the plan, so an agent knows this is a read of branding state rather than a mutation. It does not explicitly name its write sibling fillo_set_branding, but the read intent is clear from title and text.

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 statement of when to call this versus fillo_set_branding or other settings tools, and no prerequisites or context cues. The agent must infer usage entirely from the name and title.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the semantics of the two policy values, which is real context, but says nothing about auth requirements or how the value is surfaced.

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 compact sentence with no wasted words. It is reasonably front-loaded, though it reads as a noun-clause fragment rather than a full statement of purpose.

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?

An output schema exists, so return values need not be explained, and the description partially duplicates that. For a zero-parameter read tool the definition is callable, but the missing statement of what the tool actually does leaves 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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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 never states an action verb; it only enumerates the two possible policy values ('publishable_key' vs 'trusted_only'). Combined with the name/title an agent can infer this reads the code-sync policy, but the description itself does not say what the tool does, and it does not distinguish itself from the sibling fillo_set_code_sync_policy.

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 guidance on when to call this versus alternatives. The existence of fillo_set_code_sync_policy as a sibling makes a read-vs-write distinction useful, and the description offers none.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral nuance beyond that: the staged-draft result is conditional on the connection having edit rights, which the agent could not infer from the schema.

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

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

A single dense sentence front-loaded with the action and resource, with the conditional draft behavior appended after the required parts. Nothing is wasted and no sentence is redundant.

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?

Output schema exists so return values need not be spelled out, yet the description usefully summarizes them (schema, theme, status, draft). The single required parameter is fully covered and the edit-permission precondition is disclosed, so an agent has everything needed to call it correctly.

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

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

Only one parameter and schema description coverage is 100%, so the schema fully documents it. The description restates the same accepted key forms (id, slug, push handle) without adding format or precedence details, which is the expected baseline 3.

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

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

Names a specific verb (Fetch) plus resource (a project form), states the lookup key set (id, slug, or push handle), and enumerates what is returned (live schema, theme, status, staged draft). This clearly separates it from list-style siblings like fillo_list_forms and fillo_get_library_form.

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

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

Gives two concrete when-to-use cases: reading a form before editing, and verifying what fillo_push_form staged, which explicitly routes to a sibling. It does not state when-not to use it (e.g. vs. fillo_list_forms for multiple forms), so it falls short of a full 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds useful context that the returned config includes connected channels/servers for Discord, but says nothing about reversibility, auth, or other behavioral traits beyond what the annotations provide.

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

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

Two tightly worded sentences with the core purpose front-loaded and zero filler. Efficient and well-structured, though very short for a tool with several adjacent siblings.

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 an output schema present, return values need not be explained, and rich annotations cover the safety profile. The description covers the core behavior and adds provider-specific detail, leaving only sibling routing guidance as 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?

Schema description coverage is 100%, so the schema already documents both 'form' and the enumerated 'provider' parameter. The description adds only marginal meaning (framing provider as the destination that receives responses) and does not extend parameter syntax or format 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?

The description states a clear purpose — reading whether a form sends responses to a provider and how it is configured — with the title confirming the read/destination framing. It distinguishes the operation clearly but does not differentiate from adjacent siblings like fillo_enable_integration, fillo_disable_integration, or fillo_disconnect_integration.

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?

No explicit when-to-use guidance, no exclusions, and no named alternatives. The presence of several closely related integration siblings (enable/disable/disconnect) makes the absence of routing guidance a real gap, though the read framing is implied by the name and title.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'This read creates no form' largely restates the structured safety profile. The description does add useful behavioral context about what guidance the result carries (useWhen/avoidWhen, measure preservation) and the required follow-up flow, but it omits pagination/limits or failure behavior for an invalid id.

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

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

Front-loaded with the core action, then progressively adds result contents and workflow steps. Slightly dense with an enumerated list of returned artifacts, but every sentence is task-relevant 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?

An output schema exists, so naming the returned fields is partly redundant, but the description still supplies essential downstream instructions (placeholder resolution, measure preservation, using the authenticated setup/publishing flow). For a single-param read tool this is close to complete, with only edge-case/idempotency detail 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?

With one parameter at 100% schema coverage and a documented pattern plus min/max length, the schema carries the load. The description's 'exact id from fillo_search_library' matches the schema's own wording, adding little beyond it, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Retrieve one public library form by exact id') and anchors provenance to fillo_search_library, which cleanly separates it from fillo_get_form and the search tool. An agent can pick this tool without opening a schema.

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

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

Gives clear context: id comes from fillo_search_library, then 'use the existing authenticated Fillo setup and publishing flow' after resolving placeholders. It does not explicitly contrast against fillo_get_form, so an exclusion is missing, but the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one genuinely useful behavioral detail — that an empty result means any origin is permitted — but says nothing about auth scoping or result shape beyond that.

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, front-loaded sentences with no filler. The core semantics (what the value means) come first and the edge case (empty = any) second.

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 lookup with an output schema present, the description covers what is needed; return formatting is handled by the schema. It could go slightly further by noting the relationship to set_origins or the key scoping, but nothing essential 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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The schema itself is trivially complete with additionalProperties=false.

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 resource — the origins a publishable key may stage drafts from — which tells an agent exactly what this read returns. The 'get' vs 'set' verb distinction against the sibling fillo_set_origins is carried by the name/title rather than the description, so it is clear but not explicitly contrasted.

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 statement of when to call this versus alternatives, no prerequisite or permission context, and no mention of the paired fillo_set_origins that would change these values. Usage is only implied by the tool name.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds real value beyond them: the opaque id's stability across token refresh, reconnection, scope upgrades, and display-name changes, plus the meaning of the nickname field. That is meaningful behavioral context for an identity call.

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

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

Three tight sentences, front-loaded with what is returned. The stability enumeration is the longest part but earns its place by telling the agent the id is durable.

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?

An output schema exists, so return fields need not be enumerated. The description adds the identity semantics (id stability, nickname meaning) that the schema cannot convey, making it complete for a zero-param read 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?

Zero parameters, so the baseline is 4. The description correctly adds no parameter detail and instead orients the agent to the credential-derived response.

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: returns the Fillo account tied to the request's authenticated credentials. Clear on its own, but it never differentiates itself from the sibling fillo_whoami, which plausibly overlaps in 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?

No when-to-use guidance and no alternatives named. Crucially, the neighboring fillo_whoami tool is left unaddressed, so an agent gets no signal about which identity tool to pick.

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 the read-only/idempotent annotations: it discloses that file references carry only id/name/size with bytes left in customer storage, that withheld or cross-project ids silently read as not-found, and that response content is untrusted respondent input. These are non-obvious behavioral traits an agent could not infer from the schema or annotations.

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

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

Two dense sentences with no filler; the core fetch purpose, the payload shape, and the security warning are all front-loaded and each 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?

An output schema exists, so return values need not be spelled out, yet the description still characterizes the payload precisely. With annotations covering the safety profile and the untrusted-content warning covering the injection risk, nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the schema already documents the single id parameter and its source. The description adds a little semantic weight via 'accepted response' and the not-found behavior for withheld/cross-project ids, but does not extend the parameter syntax or format.

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 single accepted response by id') and enumerates the payload (answer data, meta, form version, file references), which separates it from the list-style siblings. It stops short of naming an alternative explicitly, so sibling differentiation is implied rather than stated.

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

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

Usage is implied by 'by id' plus the schema note that the id comes from fillo_list_responses, so the list-then-fetch flow is discoverable. However, the description never says when to prefer this over fillo_response_summary or the list tools, and offers no prerequisites or 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 already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the scope of the returned data, saying nothing about permissions, pagination, or freshness — enough to be useful but not rich.

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 sentence with no wasted words, and the scope of the resource is front-loaded. The comma-heavy enumeration is slightly dense but appropriate for a one-parameter read.

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

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

An output schema exists, so return values need not be explained, yet the description still previews the settings categories, which is helpful. For a simple single-parameter read with full annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'form' parameter is documented as accepting an id, slug, or push handle. The description adds no additional meaning about how to identify the form, so the schema carries the load and 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 enumerates the specific resources returned — notifications, receipts, saved progress, response limits, trust policy, and presentation keys — which lets an agent distinguish it from fillo_get_form or fillo_get_branding. It is phrased as a noun fragment rather than a verb+resource and never explicitly contrasts with those siblings, so it falls short of a 5.

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

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

There is no when-to-use statement, no prerequisites, and no mention of the write counterpart fillo_update_settings or of fillo_get_form as the alternative read path. Usage must be inferred entirely from the content list, which is effectively no guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and a closed world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it distinguishes the persisted choice from what uploads currently resolve to, and names the possible resolved targets (workspace default vs. Fillo's short-lived transit staging).

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 compact sentence with the key distinction (stored vs. resolved) front-loaded and no filler. It could be marginally clearer about the read action, 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 an output schema present, the description need not enumerate return fields, and it still characterizes the two-part answer (stored choice and effective resolution). For a one-parameter read tool with full annotation coverage, this is essentially 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% and the single 'form' parameter is fully documented in the schema (id, slug, or push handle), so the schema already does the work. The description adds no parameter-level syntax or format detail, which makes the baseline 3 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 names a specific resource (a form's file-upload destination) and what is returned (the stored choice plus the current resolved target). The action verb is only implied via the title, but the resource is unambiguous and clearly distinct from fillo_set_storage.

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

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

There is no explicit when-to-use guidance and no mention of the obvious complement, fillo_set_storage, or of fillo_get_settings. The read-only nature of the tool is inferable from the phrasing, but the agent is left to infer the routing on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the full safety profile is covered structurally. The only extra signal the description offers is the word 'connected', hinting that a HubSpot integration must be linked, but this is not stated as an explicit prerequisite and adds little beyond the structured data.

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

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

It is a single short fragment with no wasted words, but it is so terse that it reads as under-specification rather than disciplined conciseness — there is no front-loaded statement of the action being performed.

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?

An output schema exists and there are no parameters, so the description does not need to explain return values or inputs. However, for a list tool with no usage guidance, the definition is only minimally sufficient — it never states what the tool returns or when it should be used.

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

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

The tool takes zero parameters and the schema is fully described, so the baseline of 4 applies. There is nothing parameter-related the description could or should clarify.

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

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

The phrase names a specific resource ('the connected HubSpot account's Deal pipelines and stages'), which is clearer than the bare name, but it is a noun fragment with no verb — the agent must infer the 'list' action from the tool name/title. It does implicitly distinguish itself from sibling fillo_hubspot_properties (which concerns properties), so it is adequate but not explicit.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as fillo_hubspot_properties or fillo_get_integration. The agent is left to infer that this should be called before mapping deals to stages.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds a meaningful behavioral detail beyond them: only writable properties are returned, which tells the agent it won't get read-only fields and that results are safe to use for mapping.

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 identifies the resource, the constraint (writable), and the practical purpose with no padding.

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

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

With an output schema covering return values and annotations covering the safety profile, the description only needs to convey scope and intent, which it does. It could note the writable-only filter more prominently, but nothing essential is missing for a no-argument list 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?

The tool takes zero parameters, so there is nothing for the description to clarify; baseline 4 applies. The schema is empty and self-explanatory.

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 resource (the connected HubSpot account's writable Contact properties) and a concrete purpose (building a field mapping without guessing internal names). It is distinguishable from the related sibling fillo_hubspot_pipelines by naming 'Contact properties' rather than pipelines, though it does not explicitly contrast the two.

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 clause 'for building a field mapping without guessing internal names' gives a clear triggering context for when to reach for this tool. There are no exclusions or named alternatives, but the use case is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description adds context beyond that: it discloses that the secret is never returned (a security guarantee) and that the output includes a count of dependent forms. It doesn't discuss accuracy, staleness, or boundaries of the count, which keeps it from a 5.

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

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

Two sentences, both earning their place: the first states what is reported, the second front-loads an important security caveat. 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?

An output schema exists, so return values need not be explained, and with no parameters and full annotation coverage this description is nearly sufficient. The only mild gap is a lack of explicit routing to the enable/disable siblings for an agent deciding what to do with the status.

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 per the rubric the baseline is 4. The description makes no parameter claims and needs none.

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 read resource (identify() enforcement state) and the scope of what it reports (whether enforcement is on, plus how many forms depend on it). It is clearly a read-only status check, which implicitly separates it from fillo_enable_identity and fillo_disable_identity. It stops short of naming those siblings explicitly.

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

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

There is no when-to-use statement, no prerequisites, and no mention of the alternative mutation tools (fillo_enable_identity / fillo_disable_identity). Usage can be inferred from the read-only nature of the tool, but the description provides no explicit 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?

Adds real context beyond annotations: accepted formats, 512 KB cap, SVG rejection, the required public-https constraint, and dedup behavior ('Importing the same image again returns the same id'). The last point sits in mild tension with idempotentHint=false, but the annotation mostly concerns default engine classification, so this reads as useful disclosure rather than a 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?

Three dense sentences, front-loaded with the core action and constraints, then the return value and follow-up workflow. Every clause carries information an agent needs.

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

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

Complete for a one-parameter import tool: constraints, return contract, and the exact next steps are all given, and an output schema exists so return-shape detail is not needed 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?

With a single parameter and 100% schema coverage, the baseline is 3; the description goes further by constraining the URL's scheme (public https) and the accepted image types/size, which the schema's 'Public https URL of the image.' does not fully convey.

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

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

Specific verb+resource with constraints: 'Download a PNG, JPEG, or WebP image (up to 512 KB, no SVG) from a public https URL into the workspace, for a form's logo on its hosted page.' This clearly distinguishes it from generic upload/connection tools among the siblings.

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

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

Explains the context (a form's logo on its hosted page) and the downstream workflow: set the returned id as theme.logo or theme.dark.logo, then persist via fillo_push_form. No explicit 'when not to use' or alternative tools are named, so it stops 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?

Annotations already flag this as a non-readonly, destructive, non-idempotent, open-world write. The description adds context the annotations cannot express: the privilege-escalation guard ('cannot grant a role above the consenting user's own') and the human-approval-link path for ask-policy connections. It stops short of covering non-idempotency consequences (e.g., duplicate email invites) or what the destructive hint actually destroys.

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

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

Two tightly written sentences with the core action front-loaded and the two limiting constraints following. No filler, nothing redundant.

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?

An output schema and rich annotations cover return values and the safety profile, so the description needn't repeat them. The added permission and approval-policy notes make it usable, though it omits edge cases an agent might hit (already-a-member email, invite expiry/resend behavior).

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 50%: 'role' is described, 'email' is not. The description repeats the enum values (member, admin, owner) that the schema already lists, adding little, but it does contribute one genuine semantic constraint: the inviter's own role caps what can be granted. With schema doing half the work and no email format guidance, a 3 is appropriate.

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

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

States a specific verb ('Email an invitation') and resource ('join the workspace') with a scoping detail (role). This is cleanly distinguishable from siblings like fillo_change_member_role, fillo_remove_member, and fillo_list_members, which operate on existing members rather than inviting new ones.

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

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

The description implies the use case (inviting a new teammate) and states two real constraints: you cannot grant a role above your own, and ask-policy connections require a human approval link. However, it never explicitly says when to use this versus alternatives (e.g., fillo_change_member_role for existing members) or what happens on duplicate invites, so guidance is implied rather than explicit.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and closed-world behavior. The description goes beyond that by disclosing the returned content and a security guarantee ('Never returns key material'), which is genuinely useful context an agent cannot get from the schema or annotations.

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

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

Two short sentences with zero filler; the resource and its contents are front-loaded and the security caveat is compactly appended.

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 with an output schema and full annotation coverage, the description is largely sufficient. The only missing piece is disambiguation from the other list_* tools in the same family.

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 the baseline of 4 applies; the description's enumeration of returned fields adds some value even though there are no input parameters to clarify.

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

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

States a specific verb (list) and resource (MCP clients authorized against this project), and even enumerates the returned fields (scopes, approval policy, expiry). It implicitly separates itself from key/token listing tools by naming 'MCP clients', but never explicitly routes the agent away from siblings like fillo_list_api_keys or fillo_list_tokens.

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 offers no when-to-use guidance, no prerequisites, and no mention of alternative tools. In a toolset crowded with list_* siblings (list_api_keys, list_tokens, list_connections, list_members), the absence of any routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavioral context beyond that: it discloses that revoked and expired rows are included (audit-trail scope) and that key material is never returned, a security-relevant guarantee an agent could not infer from the annotation.

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 clipped sentences with zero filler; the scope and the key-material guarantee are both front-loaded and each phrase 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?

An output schema exists, so return-value structure needn't be explained. The description still covers the two things an agent would want to know: that revoked/expired entries are included and that no secrets are exposed. Slightly light on when to prefer it over adjacent key/token listing tools, but otherwise 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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter detail, as there is nothing to document.

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 the exact resource ('this project's fsk_ keys') and scopes it to the current project, which distinguishes it from sibling list tools like fillo_list_tokens and fillo_list_sync_tokens by the 'fsk_' key type. The verb is implied by the noun phrase rather than stated, but the operation is 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?

Usage is only implied: the mention of 'revoked and expired rows for the audit trail' suggests this is for auditing/reviewing keys, but it never says when to call this versus related tools such as fillo_revoke_api_key or fillo_list_tokens. No explicit when/when-not guidance is given.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description nevertheless adds meaningful context beyond them: the secret-handling guarantee ("Never returns credentials") and the shape of what it surfaces (per-project usage and dependency counts), which goes past 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?

Three tightly packed sentences with the primary purpose front-loaded, followed by the security guarantee and the field reference. Every sentence earns its place and nothing is 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 an output schema present, return formatting need not be explained, and the annotations cover the safety profile. For a zero-parameter read tool the definition is nearly complete; only explicit routing to sibling tools 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 tool takes zero parameters, so the schema carries no parameter burden and the baseline is 4 by rule. The mention of `label` describes a returned field, not an input, so it adds no parameter meaning but no harm either.

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

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

Clearly states a specific verb and resource: it enumerates the workspace's reusable provider accounts and adds what is returned (which one the project uses, dependency counts). It does not differentiate itself from adjacent read/selection tools like fillo_get_integration or fillo_select_connection, so it stops short of the 5 tier.

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 trailing note that `label` is what a removal must confirm with subtly routes the agent toward fillo_remove_connection_account, but there is no explicit when-to-use, when-not, or named alternative such as fillo_get_integration or fillo_disconnect_integration.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuinely new behavior — the opt-in gating and the refusal path — plus a trust classification ('untrusted respondent content'). That is meaningful context beyond the structured fields.

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

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

Three short sentences, front-loaded with what the tool returns, then prerequisites, then the trust caveat. No filler and nothing buried.

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?

An output schema exists, so return shape need not be explained; the description covers what it returns, the gating requirement, and the data-trust caveat. Ordering/pagination behavior is unstated, which is a minor gap for a listing 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?

Only one parameter (form) and schema description coverage is 100%, so the schema already documents it fully; the description adds no format or resolution detail for the id, slug, or push handle. Baseline 3 is appropriate.

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

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

States a specific resource and viewpoint: 'Who is mid-fill on a form and what they have typed so far,' which clearly separates this from submitted-response tools like fillo_list_responses. It does not name a sibling explicitly, so differentiation is implied rather than asserted.

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

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

Gives a concrete precondition for use: the form must have saveProgress and draftAnswersVisible opted in, otherwise a clear refusal. It does not name an alternative tool for the case where a caller actually wants submitted data, so routing guidance is partial.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds meaningful context beyond that: it reads the workspace's Google credential and requires storage:manage, which tells the agent about an auth/permission dependency it could otherwise miss.

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 with no padding and the scope (current selection + writable folders) front-loaded. Slightly jargon-heavy phrasing ('it rides storage:manage') costs a little, 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?

An output schema exists so return values needn't be described, and annotations plus full schema coverage carry most of the load. The description supplies the permission dependency and result scope, leaving little an agent would need that isn't already structured — only the exact relationship to sibling write tools is unstated.

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

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

Schema description coverage is 100%, so both parameters are already documented ('Folder name filter' and 'Form id, slug, or push handle'). The description's '(filter with q)' only restates the schema's filter semantics and adds no format or syntax detail. Baseline 3 applies.

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

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

States a specific verb+resource ('list Google Drive folders for a form') and clarifies the specific scope: the current Drive folder selection plus the connected account's writable folders. This distinguishes it from a generic folder lister, though it doesn't explicitly name the nearest sibling (fillo_set_drive_folder) as the write-side alternative.

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

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

Usage is implied rather than stated: 'filter with q' hints at narrowing results and the writable-folders framing suggests it's for picking a target folder. However, it gives no explicit when-to-use vs fillo_set_drive_folder, fillo_reset_drive_folder, or fillo_get_storage.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral detail: 'Newest first, up to 200', disclosing ordering and a result cap that the annotations do not 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?

Two tight sentences: the resource and returned fields come first, the ordering and cap last. Every clause carries information and nothing is padded.

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

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

With an output schema present, return values need not be re-explained, and the description is sufficient for a zero-argument read. The only gap is that a hard cap of 200 is stated without any indication of how to retrieve beyond it, which matters given there are no pagination parameters.

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

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

There are zero parameters, so the baseline of 4 applies; the description has no parameter semantics to add or omit, and nothing here misleads about inputs.

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

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

States a specific verb (List) and resource (forms) scoped to 'the connected project', plus the exact fields returned. It is clear what the tool does, but it never distinguishes itself from near-siblings like fillo_get_form or fillo_list_drafts.

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

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

Usage is only implied by the listing semantics; there is no explicit statement of when to reach for this versus fillo_get_form (single form) or fillo_list_drafts. The 'connected project' scoping is the one contextual cue that steers selection.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is lower; the description earns credit by disclosing that results are quarantined and never interleaved with accepted responses, that a separate tool is needed to change state, and that respondent content is untrusted. It does not cover pagination limits or ordering, but the extra context is substantive.

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

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

Three short sentences, front-loaded with the resource definition, then usage pointers, then the safety caveat. No filler and nothing 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?

An output schema exists, so return values need not be spelled out. Purpose, filter/paging inheritance, the release path, and the untrusted-content warning together give an agent everything needed to invoke this 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?

With 10 parameters at 60% schema description coverage, the schema does most of the work but leaves several undocumented. The description adds value only by pointing at fillo_list_responses for 'the same filter grammar and paging', without explaining q/where/range/cursor semantics directly, so it lands at the adequate baseline.

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 resource (responses withheld by the form's trust policy, quarantined) and explicitly scopes it as 'never mixed with accepted ones', which cleanly separates it from fillo_list_responses. An agent can pick this over its sibling 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?

Names the follow-up action explicitly ('Release them with fillo_release_responses') and points to fillo_list_responses for the shared filter/paging grammar. It lacks an explicit statement of when-not to use it, but the quarantined-vs-accepted scoping makes the selection condition 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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely useful disclosure not present in annotations: credentials are never returned. It also clarifies that both active members and pending invitations appear in the result set.

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

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

Two short, information-dense sentences with the result scope front-loaded and the security caveat second. Nothing is padded or redundant.

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?

An output schema exists, so the description need not explain the return shape, and annotations carry the safety profile. Combined with the scope and credentials note, an agent has enough to call it correctly; only usage routing is absent.

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, which is the baseline-4 case. There is nothing for the description to disambiguate, and it does not waste space inventing parameter guidance.

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 the resource precisely (workspace members with their roles) and explicitly discloses that pending invitations are also returned, which is a meaningful scope detail. It doesn't differentiate from adjacent read siblings like fillo_list_agents or fillo_whoami, but the member+invitation scope 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?

There is no guidance about when to call this versus alternatives such as fillo_list_agents, fillo_whoami, or the member-mutating siblings. No prerequisites are stated, though the tool is a parameterless read so the scenario is fairly self-evident.

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 read-only, idempotent, non-destructive safety, so the description is not carrying that burden. It still adds real value beyond them: keyset pagination behavior, scoping to non-deleted ('living') profiles, and the warning that profile fields are respondent-provided and untrusted — a substantive trust caveat.

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?

Dense and front-loaded: the entity, its fields, the filter options, paging model, and a trust warning fit in three tight sentences with no filler. Slightly terse but 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?

With an output schema present, return values need not be described, and annotations cover the safety profile. The description adds filtering, paging, and a trust caveat, making it nearly complete for a read-only listing tool; only explicit routing to sibling listing tools is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies externalId (identify() users), email (as a filter), and cursor (via 'keyset paged'), but says nothing about the limit parameter or its 1–100 range, leaving one of four parameters undocumented anywhere.

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

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

States the specific resource (living respondent profiles = identify() users) and enumerates the returned fields (external id, email, name, traits, verified flag). 'Living' usefully marks it as distinct from deleted-respondent operations and from sibling list_response tools, though it never names an alternative outright.

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?

No explicit when-to-use or when-not guidance. It mentions that you can filter by externalId or email, which implies lookup usage, but it never contrasts with siblings like fillo_list_responses or fillo_get_response, leaving the agent to infer which listing tool applies.

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 cover safety (readOnly, idempotent, non-destructive), yet the description adds substantial behavioral context beyond them: ordering (newest first), keyset pagination with cursor continuation, hard exclusion of withheld/quarantined rows, and a prompt-injection warning that response content is respondent-provided and untrusted. These are exactly the traits an agent cannot infer from structured fields.

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

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

Front-loaded with purpose and scope, and every sentence carries information (filter grammar, exclusions, paging, security). The middle sentence is dense with an enumerated grammar list, which slightly hurts scannability 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 an output schema present, return-field documentation is unnecessary, and the description covers the remaining gaps: filtering semantics, pagination mechanics, exclusion of held rows, and the untrusted-content caveat. An agent has everything needed to call and iterate on this tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds real meaning on top: it enumerates the filter dimensions (range, q, source, respondent, where), specifies the where-clause grammar fieldId:op:value, and ties the cursor parameter to a prior page's nextCursor.

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 ('List a form's accepted responses') plus two distinguishing qualifiers: accepted-only and keyset-paginated newest-first. The exclusion of withheld/quarantined rows implicitly separates it from fillo_list_held_responses without the agent needing to open 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?

It gives clear operational context: use the responses-grid filter grammar for narrowing, follow nextCursor to page, and the tool returns only accepted rows. It stops short of naming alternatives (e.g. fillo_list_held_responses, fillo_get_response) or stating when to prefer a single-response or summary tool instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the result is 'metadata only, never the token', which tells the agent no secret material is exposed — a security-relevant disclosure not present in the structured fields.

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

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

A single compact clause with no filler, and the most important constraint (stage-only, metadata only) is front-loaded. It is arguably terse to the point of being a fragment rather than a sentence, 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?

An output schema exists, so return shape need not be explained, and the description adds the one thing an agent most needs to know about the payload (no token values). It omits any mention of auth or pagination, but for a parameterless read-only list tool the definition is adequate.

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

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

The tool takes zero parameters and the schema is fully described, so there is nothing for the description to clarify. Baseline 4 applies; no parameter-level meaning is missing.

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 identifies the resource ('sync tokens') and narrows its scope ('stage-only ... for CI/servers'), which distinguishes it from fillo_create_sync_token and fillo_revoke_sync_token by implication. However, it never states the verb 'list' and reads as a descriptive fragment, so the agent must lean on the tool name to confirm the action.

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?

'Stage-only sync tokens for CI/servers' implies the context in which this tool applies and implicitly scopes out non-stage tokens. It stops short of naming the alternatives (create/revoke sync token) or stating when to call this versus fillo_list_tokens or fillo_list_api_keys, so the guidance remains implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the genuinely useful security-relevant disclosure that only metadata is returned and never the bearer token secret. It says nothing further about pagination or output shape, but an output schema exists to carry the return structure.

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 compact clause with the scope front-loaded before the enumerated token kinds and the metadata-only guarantee. Every element earns its place and nothing is padded.

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

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

For a zero-parameter, read-only lister with an output schema and full annotation coverage, the description supplies everything an agent needs: what is listed, that it is project-scoped, and that secrets are withheld. Only the sibling disambiguation against fillo_list_api_keys/fillo_list_sync_tokens 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 tool takes zero parameters, so there is no parameter semantics to describe and the baseline of 4 applies. Nothing in the description contradicts or misrepresents the empty 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?

Specific verb (list) plus a precisely scoped resource (fcli_ credentials bound to this project), and it enumerates the token kinds (CLI logins, Zapier, n8n, agent handoffs). It is not, however, differentiated from the closely named siblings fillo_list_api_keys and fillo_list_sync_tokens, so an agent cannot tell from the description alone why it would pick this over those.

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 enumeration implies the use case (enumerating connector/CLI credentials for this project), but there is no explicit when-to-use guidance and no exclusion of alternatives such as fillo_list_api_keys or fillo_list_sync_tokens. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description contributes genuine extra behavior: results are ordered newest-first and capped at 200, which is directly useful for pagination and result-set expectations.

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 carries the resource, ordering, and result cap with zero filler.

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

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

An output schema exists, so return values need not be explained, and one required param is fully documented. What remains ambiguous is the relationship to siblings such as fillo_list_drafts and fillo_publish_form: the title says 'published versions' while the description says 'every stored schema version', leaving whether drafts are included unresolved.

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 itself documents that 'form' accepts an id, slug, or push handle. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description names the resource precisely ('every stored schema version of a form') and adds scope details (newest first, up to 200) that let an agent recognize it as a version-history read. It does not, however, differentiate itself from close siblings like fillo_list_drafts or fillo_list_forms, and the verb 'list' is only implied.

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 statement of when to call this tool, when not to, or which sibling to prefer (e.g., list_drafts vs versions). The agent must infer the use case purely from the name and resource phrase.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-derivable context: signing secrets are never returned, so the agent should not attempt to recover one via this tool. It stops short of describing pagination or return shape, which the output schema covers.

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, and the field enumeration is front-loaded before the secret caveat. Every clause earns its place.

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

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

For a simple, read-only list operation with full annotation coverage, a complete schema and an output schema covering return values, the description is sufficient. The one non-obvious caveat (secrets unavailable) is stated, though it could have named the add/update siblings to fully route the agent.

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 parameter ('form') already documented as 'Form id, slug, or push handle.' The description adds no further parameter semantics, so the baseline 3 is appropriate.

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

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

The description names the resource and enumerates the returned fields (id, url, events, authentication mode), making it clearly the read/list counterpart to fillo_add_webhook, fillo_update_webhook and fillo_remove_webhook. It never states the verb 'list' in the body text (only in the title), but the resource is unambiguous and sibling-distinguishable.

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: it is the tool that reads a form's webhook configuration. There is no explicit when-to-use or when-not-to-use guidance, and no direct pointer to fillo_add_webhook/fillo_update_webhook. The note that secrets are 'shown once when a webhook is added' lightly implies the boundary against those siblings but does not state a selection rule.

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 destructive/openWorld/not-idempotent, but the description adds real behavioral context: the scope requirement, the two publish paths (direct vs per-publish review with a human approval step), and the approval link's constraints (single-use, form-bound, 15-minute expiry). This is well beyond what structured fields provide.

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

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

Front-loaded with the core action, then layered preconditions and edge cases. The approval-flow sentence is dense but each clause carries distinct, useful information; 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?

An output schema exists, so return values need no explanation. For a destructive publish operation, the description covers scope requirements, the human-approval branch, link constraints, and the no-op edge case—everything an agent needs 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?

Schema coverage is 100% and the schema already documents both form and allowBreaking, including when allowBreaking applies. The description adds no parameter-specific syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource: take a form's staged changes (or draft) live. This clearly differentiates it from siblings like fillo_unpublish_form, fillo_push_form, and fillo_discard_changes without opening their 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?

Explains the preconditions well: it requires the forms:publish scope with direct-publish policy, and connections using per-publish review instead get an approval URL. It also notes the no-op case (already-live forms with nothing staged return success unchanged). It doesn't explicitly name sibling alternatives, but the context is clear.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds genuinely useful behavior: the draft/published precedence rule and the forms:write auth requirement for unpublished reads. No return-format or pagination detail, but nothing here is a mutation risk.

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

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

Two sentences, front-loaded with what is returned and followed by the permission caveat; the parenthetical field list is dense but earns its place by promising push-compatibility. Minor density, no waste.

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

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

For a single-param, read-only tool with an output schema and full annotation coverage, the description supplies everything an agent needs: which revision comes back, that it is push-compatible, and the auth prerequisite. Nothing material 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% with a single 'form' parameter already documented as id/slug/handle, so the schema carries the load. The description's handle/schema/theme/storage/purpose list describes the *response* shape, not the input parameter, so it adds no input semantics. 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 (pull) and resource (form definition), and pins down *which* revision is returned: the newest editable one, staged draft when present, otherwise the published definition. It also says the output matches the shape fillo_push_form accepts, which tells an agent exactly what it gets. This clearly distinguishes it from fillo_get_form and fillo_list_versions.

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?

Explains the selection rule (draft-first, published-fallback) and the permission needed to read unpublished work, which gives real context for when this call will succeed versus fail. It stops short of naming a sibling alternative (e.g., get published-only via fillo_get_form), so it is clear but not fully routing.

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 the annotations (readOnlyHint=false, destructiveHint=true): describes the auto-publish permission branch and the human approval link fallback, the draft fallback when storage setup blocks publication, and the conflict-refusal behavior that protects dashboard edits. Note the handle is described as an idempotent id for the target form, which is resource identity, not a claim that the call itself is idempotent, so it does not contradict idempotentHint=false.

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

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

Front-loaded with purpose and default behavior, then the exceptions in descending priority. Sentences are information-dense with no filler, though the conflict-handling sentence is long enough that it slightly taxes readability.

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, nested-schema mutation with an output schema present, this covers the branches an agent must reason about: permission-gated publish, approval-link path, draft fallback, and revision conflicts. 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 already 100%, so the baseline is 3; the description earns extra credit by supplying workflow context the schema omits — why baseRevision is needed (dashboard edits since last push), when allowBreaking applies and that the user must confirm first, and what publish=false means contextually.

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 specific verbs (create or update) and resource (a form), and adds the key scope detail: it also publishes by default. It distinguishes itself from siblings by naming fillo_pull_form as the conflict-resolution alternative, so an agent can route correctly 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?

Explicit guidance: publish defaults true, publish=false only on an explicit draft/review request, file requests auto-stay draft when storage blocks, and the baseRevision pull-then-push flow when the owner edited in the dashboard. This is when-to-use/when-not plus named alternatives.

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

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

Annotations already declare destructive=true, idempotent=false and openWorld=true, so the bar is lower, yet the description adds real context beyond them: non-idempotent receivers will see duplicates, held responses are ineligible, and outward-facing ask-policy connections trigger a human approval link. These are the exact behavioral facts an agent needs before invoking a destructive, non-idempotent re-send.

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

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

Three short sentences, each carrying a distinct load: what it does, the duplicate consequence, and the hard exclusion plus approval caveat. The most important constraint (new delivery / duplicates) is front-loaded with zero filler.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers the duplicate risk, the held-response exclusion, and the approval path. What is missing is scope detail on the input selection (max 200 response ids, what an invalid or unknown id does) for a tool whose blast radius is every destination of a form.

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 only 50% – 'form' is documented in the schema, but 'responseIds' has no description at all, and the description text makes no reference to either parameter. With a documented gap rather than high coverage, the description should have compensated with format or limit details (e.g. the 1-200 id bound) and does not.

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

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

Specific verb ('send responses again') and resource ('every current destination') with the key qualifier that this creates a NEW delivery rather than merely retrying. It implicitly separates itself from fillo_release_responses, but it never distinguishes itself from the close sibling fillo_retry_deliveries, leaving one plausible alternative ambiguous.

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-not-to-use rule ('Held responses cannot be re-sent — release them instead') that routes the agent to fillo_release_responses, and warns about the approval-link step for ask-policy connections. It offers no guidance on when this is preferable to fillo_retry_deliveries, the nearest sibling.

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

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

Annotations cover the safety profile (destructive, non-idempotent, open-world), and the description adds genuinely new behavioral context: every released response runs the full response.created flow (owner email, respondent receipt, webhooks, integrations), and ask-policy connections require a human approval link. That explains the side effects the annotations only hint at. It stops short of stating whether partially-released batches are retry-safe.

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

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

Three short sentences, front-loaded with the action, then the consequences, then the selection mechanics. No filler or 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?

An output schema exists so return values need not be described, and the description covers side effects and the approval-link exception. The one gap is not saying what happens on partial failure or whether the human-approval path is blocking, which matters for a destructive, non-idempotent 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 coverage is 67% and responseIds carries no schema description, so the description's "Name responseIds or pass all=true" meaningfully fills the gap by clarifying mutual exclusivity and intent. The 200-item cap and the form identifier format are left entirely to 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 action (accept/release) on a specific resource (responses withheld by the trust policy), and the second sentence explains what the operation triggers downstream. An agent can distinguish this from the read-only sibling fillo_list_held_responses and from fillo_redeliver_responses 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?

"Name responseIds or pass all=true" gives concrete invocation guidance and implies the two selection modes. It does not, however, say when to prefer this over alternatives such as listing held responses first, or what prerequisite state a response must be in. Clear context, no explicit exclusions.

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