Piku

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

Adds real context beyond the annotations: the account must be connected, nothing is emailed and no invoice number is consumed at creation time, and delivery is a separate send_draft step. That is valuable given destructiveHint=true and idempotentHint=false, which on their own would suggest a riskier operation than creating a pending draft. It does not address duplicate drafts on repeated calls or what the returned draft contains.

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 key constraint (creators only) and the no-send/no-number guarantee, then the fee. It is dense but every clause carries information, though the fee sentence is slightly tangential to the calling decision and the email-condition clause is grammatically tangled.

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 tool with no output schema, it covers permissions, the draft lifecycle, error behavior, and the delivery handoff. Missing pieces are minor: what the draft response contains and whether re-invocation duplicates a draft.

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 75%, and the description still adds meaning the schema does not: client.email is the delivery target and its absence (with send_by email or both) produces needs_client_email, and send_by self emails nothing. It does not explain split versus deposit at the top level, leaving that guidance to the schema text.

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 ('Prepare an invoice to one of the creator's clients as a Draft') and pins the resulting state as a Draft rather than a sent invoice. It clearly separates itself from the send_draft sibling but says nothing about create_quote, so the quote-vs-invoice split is left to the name alone.

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: creators only, on their own account, and the draft becomes visible to the client only via send_draft after the creator approves. It also states the client.email precondition with the needs_client_email outcome. It stops short of naming create_quote as the alternative for pre-sale documents, and the deposit-vs-split choice is only covered inside the schema.

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 substantial context beyond the annotations: it creates a Draft only, sends nothing, uses no invoice number, requires client.email unless send_by allows otherwise, and routes actual delivery through send_draft. These details clarify the safety profile and workflow despite destructiveHint=true indicating a write operation.

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

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

The description is dense but front-loads purpose and prerequisites, and most sentences add distinct operational value. A few clauses are run-on, but for a 10-parameter nested tool the size is appropriate.

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

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

Given the complexity, high schema coverage, and no output schema, the description is complete enough: it covers authentication context, draft behavior, email requirements, send_by self, non-sending semantics, and what the tool returns.

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 already 90%, so the schema carries most parameter detail. The description adds meaningful semantics for client.email, send_by self, billing options, Lines, and split, but does not elaborate on deposit, due_days, or lines_per beyond the schema.

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

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

States a specific verb and resource: prepare a quote as a Draft for one of the creator's clients. It names the core components (Lines, billing options, payment terms, split) and distinguishes itself from send_draft by clarifying that this tool does not send anything.

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 prerequisites (creators only, own Piku account) and explicitly says the draft reaches the client only through send_draft after review. It also explains the client.email requirement and the needs_client_email response, though it does not directly contrast with create_invoice.

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

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

Goes well past the annotations by clarifying the draft/live distinction ('Nothing on the live page changes: the creator previews the Page draft and applies it, or parts of it') and the destructive nuance ('A new design replaces the open one'), which explains the destructiveHint flag concretely. It also states the return payload (draft_id, changes by part, preview_url), closing the gap left by having no output schema.

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

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

The critical constraints — creator-only access and what a design may contain — are front-loaded, and each subsequent sentence (optionality, draft safety, returns) earns its place. The one cost is the sprawling comma-and-parenthesis enumeration of designable parts, which is dense but still parseable.

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 10-parameter, zero-required, deeply nested mutation tool the description covers scope, permissions, partial-update behavior, draft safety, and return values. Remaining gaps are minor: no guidance on obtaining ids from get_page or on what happens to an existing draft's unnamed parts beyond the general replacement note.

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 field semantics are already carried by the structured data. The description adds the cross-cutting rule that omitted fields are preserved and that only creator-supplied links or numbers may be used, but it adds little per-parameter meaning beyond that; baseline 3 applies.

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

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

Names a specific verb and resource: 'Propose a design for the creator's page as a Page draft', then enumerates exactly what the design may cover (look, bio, titles, order, widgets, sections, Rates, groups, Portfolio). An agent can distinguish this from send_draft or get_page without reading 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?

'Creators only, on their own Piku account (asks them to connect)' establishes the prerequisite, and 'Every field is optional; give only what changes' defines the partial-update contract. No sibling is named as an alternative or a required prior step, though get_page appears in the schema as the id source — that routing is left implicit in the description body.

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 useful behavioral context by listing the possible request statuses and noting that quote total, currency, and the brand's approval link are included when the request is quoted.

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

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

The definition is two efficient sentences. The status enumeration is front-loaded, and the instruction about deal_id follows immediately with no wasted text.

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

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

For a simple read-only getter with one required parameter and no output schema, the description covers the core purpose, status values, ID source, and conditional quote fields. It does not explain error behavior for invalid IDs or the full return shape for non-quoted statuses, but it is largely complete for an agent 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?

Schema description coverage is 100%, and the schema already documents deal_id as 'The request_id from submit_request.' The description reinforces that mapping but does not add syntax, format, or validation details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states that this tool returns the current status of a request, enumerating the possible statuses. It also maps deal_id to the request_id from submit_request, which helps distinguish it from broader listing tools like list_deals. However, it does not explicitly name a sibling tool as an alternative or contrast.

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

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

The description implies the tool should be used after submit_request by telling the caller to pass the request_id from submit_request as deal_id. It does not state when to prefer this over list_deals or get_invoice, nor does it include any exclusions or prerequisites beyond the ID source.

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 the description still adds substantive context beyond them: a connect/auth prerequisite, the 'newest first' ordering, an explicit privacy guarantee ('Counts only, never who bought or came'), and a failure message when Events is not open on the account.

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 audience and prerequisite, then a compact field list with a privacy caveat and a failure case. Dense but not padded; the parenthetical '(asks them to connect)' is slightly awkward but earns its place by flagging the auth flow.

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

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

There is no output schema, and the description compensates by enumerating the returned fields and the ordering, plus saying what happens when Events is unavailable. The one real gap is input behavior — how status filtering and limit interact with the 'newest first' ordering is left unstated.

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

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

Schema description coverage is 0% and the description does not compensate: neither the `limit` cap nor the `status` filter is explained. 'status (draft, on_sale, ended, cancelled)' appears only as a returned field, so an agent cannot tell from the description that a status enum exists as a filter input, and 'newest first' only indirectly implies what limit does.

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 ('the connected creator's ticketed events') and then enumerates exactly what comes back: title, dates, status, public link, tickets sold, ticket sales, check-ins. No sibling tool covers events, so it is trivially distinguishable from the invoice/quote/deal/page tools listed.

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

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

Explicitly scopes the audience and prerequisite — 'Creators only, on their own Piku account (asks them to connect)' — and covers the degraded case when Events is not open on the account. It stops short of stating when to prefer this over any alternative or which statuses to request, but no competing events tool exists.

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, closed-world, so the safety profile is covered. The description adds real value beyond that: the auth/connection requirement for creators and an enumeration of what comes back (Lines, amount, status, due date, period, receipt, pay link). It doesn't say what happens when the number doesn't exist, 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 short sentences with no filler, audience constraint front-loaded before the operation. The second sentence is slightly fragmentary but every clause carries information.

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

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

For a simple single-record read with no output schema, the description covers scope, precondition, and the shape of the response. Only the error path (unknown invoice number) is unaddressed, which is a minor gap given the richness elsewhere.

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

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

Schema coverage is 100% and the single parameter is already documented with the same INV-0042 example, so the description adds no new meaning beyond the schema. Baseline 3 applies for a one-param, fully documented tool.

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

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

States a specific resource and scope — a single invoice fetched by its number, with the identifier format (INV-0042) spelled out. The singular 'One invoice' implicitly separates it from list_invoices, but no sibling is named explicitly, so it stops short of a 5.

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

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

'Creators only, on their own Piku account (asks them to connect)' is a concrete eligibility and precondition statement, which is more than most read tools offer. There is no explicit when-not or named alternative, but the single-vs-list distinction is clear from the phrasing.

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

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

The annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description need not repeat safety. It does add genuinely useful context beyond them: the creator must have connected their Piku account, and the read returns an 'open Page draft' alongside published state. It stops short of describing pagination or size limits, which matters less for a single-page read.

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

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

The permission/identity constraint is front-loaded in the first sentence, which is the right ordering. The second sentence is a long comma-spliced enumeration of returned fields; it earns its length by standing in for a missing output schema, though it could be structured as a list for faster scanning.

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

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

With no output schema, the description must convey what comes back, and it does so concretely across page settings, tabs, links, widgets, Rates, groups, Portfolio and drafts. For a zero-parameter read tool this is close to complete, with only the response shape (single object vs nested arrays) left implicit.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The field enumeration is better read as return-value documentation than as parameter meaning.

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

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

The description names a specific verb and resource ('The connected creator's public page as data') and enumerates the returned content, so the purpose is unmistakable. It does not explicitly contrast with siblings such as design_page or list_page_drafts, 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?

It states the prerequisite audience and auth condition ('Creators only, on their own Piku account (asks them to connect)'), implying when the tool is available. However, it never says when to call this versus design_page (which presumably mutates the same page) or list_page_drafts, leaving the agent to infer 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description's real contribution is return-shape context: every Rate carries a stable id, a price expressed under one of three visibility modes (full, from_price, request_only), inclusions, and self-reported audience. That visibility-mode detail is genuinely useful and not derivable from the schema. It stops short of saying what happens when a creator has no rate card.

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 dense, front-loaded sentence with no filler; the resource is named first and the contents follow. It is a noun-phrase fragment rather than a sentence, which slightly weakens readability but wastes nothing.

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

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

With no output schema, the description carries the burden of describing returns and does so well: ids, price visibility modes, inclusions, audience. Annotations cover the safety profile. The main missing piece is the edge case of a creator with no published rate card, which an agent would want to know before calling.

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

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

Only one parameter, and the schema documents it at 100% coverage ('The creator's Piku handle, like nia'). The description adds only the possessive framing ('a creator's Rate Card'), which does not extend the schema's meaning, 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 (a creator's Rate Card and media kit) and enumerates its contents: rated items with stable ids, price visibility modes, inclusions, and audience. It is clearly distinguishable from invoice/deal/page siblings, though it never contrasts with search_creators, which also takes a creator handle.

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: given a creator handle, this returns their pricing and audience data. There is no explicit when-to-use statement, no mention of prerequisites (does the creator need a published rate card?), and no routing against siblings like search_creators or get_deal.

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, yet the description still adds real context beyond them: the creator-only authorization requirement, the connection prompt, the account scoping, and the fact that a missing wallet produces a stated response rather than an error. The main undisclosed behavior is the size/ordering of 'latest withdrawals' — how many are returned and whether there is any paging.

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 tight paragraph with the audience constraint front-loaded, followed by the returned data and then the safety boundary — good ordering with no filler sentences. The middle sentence is long and colon-heavy, packing five distinct return elements into one run-on, which slightly hurts scanability.

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

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

With no output schema, the description carries the burden of describing return values, and it does so concretely, including the withdrawal status vocabulary (Asked, Approved, On hold, Sent, Received, Paid, Failed) and the available-vs-pending balance distinction. It stops short on volume/ordering of the withdrawals list and on currency or amount formatting, which are the remaining gaps for a zero-parameter 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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to add. Nothing in the text conflicts with 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?

The description names the resource (the connected creator's Piku Wallet) and enumerates exactly what it returns: balance by currency with available/pending split, total withdrawn, latest withdrawals with status, and the minimum withdrawal amount. It also states the read-only boundary ('it cannot withdraw or move money'), so an agent knows precisely what class of operation this is, and no sibling tool in the list overlaps with wallet data.

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

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

It gives an explicit audience and precondition — 'Creators only, on their own Piku account (asks them to connect)' — which tells the agent when the call will succeed and that a connection prompt may occur. It also covers the degenerate case ('When the wallet is not open on the account, says so'). It lacks explicit when-not/alternative routing, but no sibling tool is a plausible substitute, so the omission is minor.

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 this as read-only, idempotent, non-destructive, and not open-world. The description adds meaningful context beyond that: the connected-account auth prerequisite, newest-first ordering, inclusion of unsent Drafts, and returned fields. It still lacks pagination or limit behavior, so it stops short of full transparency.

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

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

The description is short, front-loaded, and each sentence carries useful information about audience, account state, ordering, included drafts, returned fields, and filters. It could be slightly more structured, but there is no wasted text.

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

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

There is no output schema, and the description does a good job listing the returned fields and the newest-first ordering. The main remaining gap is the limit parameter and pagination behavior, which an agent may need in order to call the tool correctly.

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

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

The description says results can be filtered by client name or stage, which maps to two of the three parameters. However, schema coverage is only 33%, and the description does not explain the stage enum values, the limit parameter, or pagination behavior.

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

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

The description states a specific verb and resource: listing the connected creator's Deals and unsent Drafts, newest first, with summary fields. It is clear what the tool returns, but it does not explicitly differentiate itself from siblings such as get_deal or list_invoices.

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

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

It gives clear usage context: creators only, on their own Piku account, and requires the creator to connect. It also notes filtering by client name or stage, but does not explicitly state when to use this tool instead of get_deal or other listing 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 cover readOnly, idempotent, non-destructive and closed-world, so the description correctly spends its words elsewhere: the connect/auth requirement, newest-first ordering, and the archived-exclusion rule that a caller could not infer otherwise. It does not describe pagination or what happens when more results exist than the limit allows.

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 no filler, led by the eligibility/auth constraint before the payload description. The parenthetical "(asks them to connect)" is slightly awkward but still information-bearing rather than 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 no output schema, the description usefully enumerates the returned fields and ordering, and it documents the auth gate and archived behavior. The gap is filter and page-size semantics for the three optional parameters, which an agent needs to use them 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 0%, so the description carries the full burden and largely fails: it never says that `client` filters by client name, that `status` narrows results, or that `limit` caps page size (default 20, max 50). Listing the status values only echoes the enum already in the schema, and "client" appears as an output field, which may mislead an agent about the parameter.

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

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

States a specific verb and resource (list the connected creator's invoices) and immediately enumerates the returned fields and sort order, so an agent knows exactly what it gets. It also distinguishes itself from get_invoice by explaining that archived invoices are excluded from this list but still readable individually.

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?

"Creators only, on their own Piku account (asks them to connect)" gives a clear precondition, and the closing clause routes single-invoice lookups to get_invoice. It stops short of explaining when the client/status/limit filters should be applied, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the description's added value is the auth/connection requirement ('asks them to connect'), which is genuinely useful context not in the structured fields. It also names the status lifecycle (draft, applied, discarded, replaced, expired), helping the agent interpret results, though it says nothing about result volume or pagination despite the limit parameter.

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

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

Two compact sentences with zero filler, and the access constraint is front-loaded before the payload description. Slight weakness: it opens with an eligibility clause rather than a verb stating the action, so the purpose arrives in the second sentence.

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

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

For a one-parameter read tool with full annotation coverage and no output schema, the description does the important remaining work: access prerequisites and the shape of returned data. The main gap is that ordering and result-size behavior around limit are left unstated.

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

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

The single limit parameter has 0% schema description coverage, so the description carries the full burden and does not compensate: it never explains what limit controls, its default of 10, or the max of 20. The only hint is the word 'recent', which loosely implies newest-first ordering, but that is not stated.

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

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

The description clearly identifies the resource: the connected creator's recent Page drafts, and even enumerates the returned fields (status values, applied parts, preview link). It does not explicitly name a sibling it differs from (e.g., get_page for a single design, design_page for creating one), but the plural 'drafts' resource makes the distinction inferable.

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?

'Creators only, on their own Piku account' establishes who can call it and the connection prerequisite. There is no explicit statement of when to prefer this over get_page or how it relates to send_draft / design_page, so the usage boundary 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 readOnly/idempotent/non-destructive, and the description adds substantive behavior beyond them: fuzzy-match priority order (chosen niches, then bio and Rates; city/country, then bio), cross-currency comparison for max_from_price, and the silent exclusion of price-on-request creators. It stops short of stating page size or result ordering, 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?

Four dense sentences, front-loaded with purpose, then filter semantics, then the exclusion edge case, then the pagination contract. Nothing is repeated from the schema and no sentence is filler.

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

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

For a 5-param search tool with no output schema, the description covers filtering, edge cases, and how to page. The one remaining gap is that it never indicates what a creator result contains, though the pagination hint partially offsets the absent output schema.

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

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

At 60% schema coverage the description meaningfully compensates: it explains where 'niche' and 'location' are matched, that max_from_price is a starting price converted into the creator's currency, and that cursor is the previous response's next_cursor. Only 'platform' gets no meaning beyond the schema's 'Platform of the Rate'.

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 ('Find creators with a live Piku page') and enumerates the exact facets it searches on: niche words, location, platform, and starting price. The 'live Piku page' qualifier scopes the result set precisely, so an agent knows exactly what population this returns.

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

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

The scope statement plus the pagination contract ('pass next_cursor back as cursor') make clear this is an iterative search/list tool, and the max_from_price exclusion rule tells the agent when a filter silently narrows results. No sibling alternative is named, but none of the listed siblings offers creator search, so there is no real ambiguity to resolve.

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 destructive/openWorld/idempotent, and the description adds real substance on top: the auth handshake ('asks them to connect'), what actually happens on send (accept link for quotes, numbering plus pay link for invoices), and the concrete idempotency consequence ('Sending the same Draft again sends nothing'). That is materially more than the hints convey.

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

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

Front-loaded with the actor restriction and the core action, followed by outcome and guard clauses; every sentence carries information. Slightly dense in the parenthetical about connect and send_by self, which costs a bit of 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 a destructive, outward-facing action with no output schema, the description covers who may call it, auth requirements, side effects, and idempotency. The only gap is the unexplained 'send_by self' mode, which has no corresponding schema field.

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 draft_id parameter is documented as the value returned by create_quote or create_invoice. The description adds only 'one Draft' of context, and it references a 'send_by self' mode that does not exist in this schema, so it neither compensates nor misleads at the parameter level.

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 ('Send one Draft to its client') and then spells out the divergent outcomes for a quote versus an invoice. This clearly separates it from the sibling creation tools create_quote and create_invoice, which make the objects rather than dispatch 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?

Explicit preconditions are given: creators only, on their own connected Piku account, and only after the creator has seen the Draft and approved sending. It also warns that re-sending is a no-op. It stops short of naming a sibling alternative (e.g., list_page_drafts to find the draft), so a 4 rather than 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?

Adds real behavioral context beyond the annotations: Piku emails the brand a confirm link, the request only reaches the creator's Deals after confirmation, and the window is 48 hours, and it returns a request_id. It does not spell out what happens if the 48 hours lapse unconfirmed, nor warn that repeated calls each send another email (relevant given idempotentHint=false and destructiveHint=true).

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

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

Four short sentences, front-loaded with the action and the asynchronous confirmation mechanism before the input list and return value. Every sentence carries information an agent needs; nothing is 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?

For a non-idempotent, destructive, open-world mutation with a nested object and no output schema, the description covers the asynchronous two-step confirmation, the 48-hour expiry, the required inputs, and the return value (request_id). Permissions details (e.g., whether the user must own the creator) are the only notable omission.

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

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

With only 50% schema description coverage (handle and the nested brand fields are undocumented in the schema), the description usefully enumerates all required inputs — handle, Rate id, brand name, contact email, and a short brief. The phrase 'as the user gave them' adds non-obvious meaning: pass user-supplied values verbatim rather than fabricating them. It stops short of format/length guidance for handle or brand.

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: sending a brand's request on one Rate of a creator, which is distinct from sibling creation tools like create_invoice, create_quote, or design_page. It does not explicitly name an alternative tool or a boundary condition against those siblings, so differentiation is inferred 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 the phrasing ('on one Rate', needing a Rate id from get_rate_card) but there is no explicit when-to-use or when-not-to-use guidance, nor any reference to siblings such as design_page or send_draft. An agent could reason out the flow from the confirm-link explanation, but it must infer it.

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