Method CRM MCP by usefulapi

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds a useful cost hint ('Cheap') and the backing GET endpoint, but says nothing about rate limits, response shape beyond an implied count, or filtering behavior on large tables. Useful but modest added value over 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 tight sentences with the purpose front-loaded, followed by the cost/workflow tip and the endpoint. Nothing is redundant and 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 two-parameter, read-only count tool with no output schema, the description covers purpose, filter reuse, and cost guidance. The return value (a count) is implied clearly enough, though the exact response envelope is not spelled out.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by noting the filter uses the same syntax as method_query_records — context the schema's bare 'Filter expression' lacks. The table parameter is left to the schema, which documents it well.

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: counting records in a table, with an optional filter. It names method_query_records in passing, which implicitly separates it from the record-returning sibling, though it never explicitly contrasts the two. An agent can identify it as the count-only tool 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?

'Cheap: call it before paging through a big table' gives an explicit when-to-use condition and a practical workflow context. It also points to method_query_records for the filter syntax, tying it to the alternative. It doesn't state when NOT to use it, keeping it 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?

Goes well beyond the annotations: discloses that captions can be silently dropped, that Method requires an assignee on standard accounts, that the reply re-reads the activity so links can be verified, and that no email is sent. These are non-obvious server-side behaviors an agent would otherwise only discover by failing.

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 mutating nature with 'WRITE:' and then packs id resolution, the caption pitfall, auth requirement, return behavior, and side effects into dense, non-redundant sentences. 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 8 parameters, no output schema, and no enums, the description compensates fully: it identifies required inputs, explains id lookup, warns about the silent-drop trap, and describes the response ('re-reads the activity'). Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real cross-field meaning: contact_id is the Contact's RecordID 'not the Customer's', the note body goes in Comments, and activity_type_id should be preferred over activity_type. It does not cover due, status_id, or assigned_to_id beyond what the schema says.

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 'WRITE: logs an activity (call, email, to-do, note) on a customer/lead', giving a specific verb, resource, and enumerated subtypes. An agent can immediately separate it from siblings like method_list_activities and the generic method_create_record.

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 actionable routing advice: prefer activity_type_id over the caption because 'a caption that matches zero or several options is silently dropped', and points to method_list_contacts and method_get_table_fields for resolving ids. It doesn't explicitly say when to use this versus method_create_record, but the context is otherwise 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 flag non-idempotent, destructive and open-world, but the description adds real consequences: a second call creates a duplicate record, a full customer also appears in QuickBooks/Xero, and a primary Contact record is created as a side effect. That side-effect disclosure is genuinely beyond the structured fields. The remaining gap is the response shape, which is only partially described (contact_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 a 'WRITE:' marker and the core purpose, then the mode distinction, then the side effects and prerequisites. Every sentence carries information, though the heavy parenthetical nesting makes it dense 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?

For a 9-parameter nested-object write tool with no output schema, the description covers the risky parts: duplicate creation, accounting sync, auto-created Contact, and how to address extra_fields. It stops short of describing the full returned payload (e.g. the customer's own id field name), which matters with no 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?

Schema coverage is 56%, and the description compensates for the most consequential parameters: is_lead's sync semantics, name's requiredness and formatting, and extra_fields' exact-name/case-sensitivity behavior plus the `_RecordID` convention for dropdown fields. email, phone, first_name, last_name and lead_status are left to the schema, which is tolerable since they are largely self-describing.

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 concrete verb and exact target ('creates a record in Method's Customer table') and immediately differentiates the two modes of the resource (lead vs full customer synced to QuickBooks/Xero). An agent can tell this apart from the generic sibling method_create_record 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?

Gives explicit routing: search first with method_search_customers because the call is not idempotent, and use method_get_table_fields to discover valid extra_fields names. It also gives a conditional naming rule (use "First Last" when there is no company) and tells the agent to link activities via contact_id rather than the customer id.

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

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

Adds substantial context beyond the annotations: wrong field names are silently ignored, accounting records trigger a QuickBooks/Xero sync side effect, and the call returns the new RecordID. The 'Not idempotent' sentence merely restates idempotentHint=false, and the destructive/openWorld traits are left to the annotations, but the silent-failure and external-sync disclosures are the kind of thing annotations cannot convey.

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

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

Front-loaded with the operation class and verb, then layered constraints in descending importance; nearly every clause is actionable. The example lists (Estimate, Invoice, Item, Vendor) are somewhat expendable given the schema's own examples, keeping it just short of a 5.

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 2-parameter but nested/any-table mutation with no output schema, it covers everything an agent needs: eligibility check, field-name resolution, dropdown encoding, unsupported child lines, external sync consequences, and the returned RecordID. Nothing material is left to inference.

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 exact-name matching, case sensitivity, silent-ignore behavior, and the `_RecordID` integer convention for dropdowns. The description restates the same guidance rather than adding new syntax or format detail, 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?

Starts with an explicit category marker and verb+resource ('WRITE: creates a record in any table that allows it'), then narrows scope immediately: customers/leads and activities go to dedicated tools, child lines are unsupported here. An agent can distinguish this from method_create_customer, method_create_activity, and method_update_record 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?

Gives explicit when-to-use (any table where method_list_tables shows canCreate), when-not (Customer/lead and Activity records, InvoiceLine child lines), and the prerequisite ordering (call method_get_table_fields before creating). It even names the alternative tools rather than leaving the agent to 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: what fields come back (id and name), that it doubles as a cheap credential/health check, and the underlying endpoint. It doesn't say what an invalid key returns, which keeps it below 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?

Three short, front-loaded fragments with no filler. The opening 'Who the API key acts as' is slightly elliptical in isolation but the following clause disambiguates immediately.

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

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

For a zero-param read tool with no output schema, the description covers the essential contract by naming the returned fields and the auth-check use case. Error behavior for an invalid key is the only meaningful 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 is 4. The schema and annotations are complete for a no-arg call.

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

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

States a specific verb+resource: returns the Method user (id and name) that the API key authenticates as. No sibling tool does identity lookup, so the distinction is clear, and the endpoint 'GET /api/v1/me' reinforces the exact semantics.

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 uses: resolving the id to use as an assignee, and verifying the key works. This is clear context for when to call it, though it doesn't state exclusions or name alternatives (there are none obvious among 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?

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds substantial behavioral context beyond that: the link is temporary and valid for 20 minutes, it works without an API key, and it should only be shared with someone authorized to see the file.

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-loads the key fact (temporary download link valid 20 minutes), then covers the parameter source, security caveat, and endpoint. Every sentence adds useful information without repetition.

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

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

For a simple one-parameter read operation with no output schema, the definition covers what the tool returns conceptually, how long the link lasts, where the file id comes from, and the sharing security constraint. Nothing needed 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%, so the file_id description already explains that it is a GUID. The description adds useful provenance by specifying that the id comes from method_list_files, which helps the agent obtain a valid value before calling.

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: get a temporary download link for an attached file. It also names the sibling tool where the required file id comes from, so the agent can distinguish this from method_list_files and other list/get tools.

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

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

It clearly establishes the prerequisite by saying the file id comes from method_list_files, and it gives a sharing constraint: share the link only with someone allowed to see the file. It does not explicitly state when not to use this tool or name a true alternative, so it falls short of the full 5 criteria.

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 read-only annotations, it discloses important behavior: omitting `select` can return hundreds of columns, `expand` embeds at most 50 child rows, and parent records are not expanded. That is meaningful call-shaping context for an agent.

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 front-loaded with the core operation and then efficiently packs parameter guidance into a few dense but useful clauses. 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?

With annotations covering safety and the schema covering parameter details, the description supplies the remaining behavioral context needed to call this tool correctly, including return shape hints and expansion limits.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds cross-parameter meaning, especially the child-vs-parent `expand` distinction and the `Entity_RecordID` workaround for parents, though much of it overlaps with 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 specific verb and resource: get one record by RecordID from any table. It clearly distinguishes this from list/query siblings by emphasizing a single record keyed by RecordID.

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 for using RecordID and explains when to use `select` and `expand`, including that only child tables are expandable. It does not explicitly name alternatives such as `method_query_records`, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral trait: field names are case-sensitive and wrong names are silently ignored — a failure mode an agent could not infer from annotations. It stops short of auth or rate-limit context, so not 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, front-loaded with the returned fields, followed by the usage rule and the silent-failure caveat. The trailing GET path is compact and useful for debugging; 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?

One required parameter, read-only annotations, and no output schema — the description compensates by enumerating the shape of the returned field metadata, which is exactly what an agent needs before relying on the response.

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 states the table name must match what method_list_tables returns, with the regex pattern and examples. The description adds no format or naming detail beyond that, 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+resource ('The exact field names of a table') and enumerates the metadata returned (type, required, creatable, mutable, dropdown reference table). It is clearly distinguishable from the sibling method_list_tables, which returns tables rather than fields.

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

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

Explicitly says when to use it: to pick `select` fields and to supply field names in create/update calls. It does not name the alternative tool to call for a different need, but the usage context is concrete enough that an agent knows the trigger condition.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the bar is lower, and the description still adds real operational context: results are newest-first, the note body lives in the Comments field, and omitting `select` returns hundreds of columns per row. It does not describe pagination behavior, though the schema covers that via next_skip.

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 purpose and ordering, followed by filtering, a field-location note, and a schema-hint. Every sentence carries information an agent could act on; nothing is redundant with the name or annotations.

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 read-only list tool with 7 fully documented parameters and no output schema, the description supplies the missing context an agent needs: default ordering, field defaults, and the note-text location. Only minor gaps remain, such as result shape and total-count 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 100%, so the baseline is 3, but the description adds meaning: due_after/due_before are framed as a due-date window, entity_id is tied to 'the entity they belong to', and `select` is explained as an override for the default field set. It does not clarify interaction semantics such as whether filters combine with AND.

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 and enumerates the activity subtypes (calls, emails, to-dos, notes) plus the default ordering (newest first), which lets an agent distinguish it from list tools for other record types. It does not differentiate itself from the generic sibling method_query_records, 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?

Gives concrete usage context: filter by entity, assigned user, or a due-date window, and route to method_get_table_fields to discover field names for `select`. No explicit when-not-to-use guidance or comparison against the generic query sibling, 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (RecordID, name, email, phone, entity link, active flag), which is useful since there is no output schema, but it says nothing about pagination behavior or result caps beyond what the schema's top/skip already state.

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: capability first, filter semantics second, the RecordID caveat third. No repetition of schema constraints and no filler; even the endpoint reference is a single trailing clause.

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

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

For a five-parameter, zero-required read tool with no output schema, the description covers what is listed, how to scope it, and the return fields, while pagination and field selection are fully documented in the schema. An agent has everything needed to call it correctly on the first attempt.

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, and the description goes further by clarifying that entity_id is the Customer/Vendor RecordID and warning not to confuse it with a Contact's RecordID — a semantic distinction the schema does not spell out. It adds no extra detail on select or text beyond the schema wording.

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 contacts (people)') plus the two filtering modes (entity_id scoping, text matching) and names the backing endpoint. It is immediately distinguishable from siblings such as method_search_customers or method_list_activities, which operate on different resources.

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 two ways to narrow the list and gives a concrete downstream rule of thumb ('Use a Contact's RecordID (not the Customer's) when linking activities'). It does not, however, say when to prefer this over method_query_records or method_search_customers, so tool selection across siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds the return payload shape and the follow-up call pattern, which is real value beyond the annotations; only pagination/limits are unaddressed.

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 segments: what it does, what it returns, and how to chain it — front-loaded with zero filler. The trailing 'GET /api/v1/files' is a compact implementation hint that some agents find useful.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields. For a read-only two-param tool whose annotations cover safety, the only omission is whether results are paginated or bounded.

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

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

Schema description coverage is 100% — both 'table' and 'record_id' are documented in the schema, including the pointer to method_list_tables. The description adds no parameter-level detail, 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?

States a specific verb and resource ('List the files attached to a record') plus the exact fields returned (name, size, adder, id). An agent can immediately distinguish it from siblings like method_get_file_url or method_get_record.

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?

Clearly positions the tool as the discovery step before method_get_file_url ('Use the id with method_get_file_url'), which is an explicit alternative chaining cue. It doesn't state when not to use it (e.g., for a single known file id), but the workflow 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds that results come newest-first, what field set is returned by default, and the caveat that omitting `select` returns hundreds of columns. It does not discuss page size/next_skip behavior, but the schema documents 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?

One dense sentence with the core behavior front-loaded, filters in the middle, and the alternative-tool routing at the end. No filler or repetition of schema mechanics.

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 does its job by listing the returned fields and the default-column caveat. Pagination (next_skip/top/skip) is left entirely to the schema, which is acceptable but the one remaining gap for a paged 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?

Schema coverage is 100%, so baseline is 3, but the description adds interpretive meaning: what counts as unpaid (BalanceRemaining > 0), that customer_id is a Customer RecordID, that created_since needs a timezone-bearing ISO timestamp, and that `select` overrides the default field set. This is real value beyond 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 (list invoices) along with ordering (newest first) and the optional filters it supports, and explicitly distinguishes itself from method_query_records for aggregates. An agent can tell exactly what this tool returns 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 concrete conditions for each filter (unpaid = BalanceRemaining > 0, customer_id = Customer RecordID, created_since = ISO time) and names the alternative tool (method_query_records with `apply`) for totals. Routing guidance is explicit rather than 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful context beyond those annotations by explaining that tables vary per account and that results include source and create/update/delete capabilities, though it does not mention authentication, pagination, or rate limits.

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 sentences are front-loaded with the main purpose, followed by the key usage condition and the endpoint. Every sentence adds useful information without 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 zero-parameter, read-only metadata tool, the description is complete enough: it explains what is returned, why account-specific results matter, and when to call it. Although there is no output schema, the return contents are described sufficiently for correct invocation.

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

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

The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics that need explanation. The baseline for a zero-parameter tool is 4.

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 every table on the Method account, including standard QuickBooks/Xero/Method and custom tables. It also clarifies that the response includes source and CRUD capabilities, which distinguishes this metadata-listing tool from sibling query/get tools.

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

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

It gives clear usage context: "call this before querying a table you are unsure of," because tables differ per account. It does not name an alternative sibling or state when not to use this tool, 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 declare readOnlyHint/destructiveHint/openWorldHint, yet the description still adds real behavioral detail: the default RecordID-ascending ordering that guarantees stable paging, the next_skip paging contract, and the warning that omitting select returns hundreds of columns per row. It omits the response envelope shape, but that is a minor gap against otherwise strong disclosure.

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 and the mandatory `select` rule, then the two most error-prone syntax surfaces (filter, apply) with examples. Dense but almost every clause carries operational value; the trailing raw endpoint `GET /api/v1/tables/{table}` is the one piece that may not earn 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 7-parameter, output-schema-less query tool with a non-trivial filter/aggregation DSL, the description supplies the syntax, the paging pattern, the default sort and the select requirement. It does not explain the returned fields (rows array vs next_skip vs aggregate result shape), which an agent would still have to discover at call time.

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 goes beyond it by documenting the OData filter grammar (quoting, date format, operators, functions) with a worked example and by showing both aggregate and groupby forms for `apply`. Only `top`/`skip` semantics are left entirely to the schema, which already handles them.

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

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

States a concrete verb+resource ("Query any table") and enumerates the table families it covers, making clear it is the generic table reader. It does not explicitly contrast itself with siblings like method_get_record or method_list_contacts, so an agent must infer that those are single-record or pre-filtered alternatives.

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 concrete in-tool usage rules ("Always pass `select`", "page with next_skip", apply "instead of listing rows") which implicitly tell the agent how to call it. It never says when to prefer this over method_get_record, method_list_* or method_search_customers, so tool-selection guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavior: it lists the default return fields, warns that omitting select returns hundreds of columns, and explains pagination via next_skip. It does not cover auth or rate limits, but that is a minor gap.

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 sentences, front-loaded with the core purpose, followed by return details and pagination, ending with the endpoint. Every sentence contributes useful 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?

Given six optional parameters, no output schema, and annotations that cover safety, the description is complete: it explains what is returned by default, how to customize fields, how pagination works, and where to find field names. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description reiterates text and kind usage and mentions select and skip (as next_skip), but adds no semantics 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?

The description clearly states a specific verb (Find) and resource (customers and leads), and scopes the search to text, type, or listing all. It does not explicitly distinguish this search from the generic method_query_records sibling, so sibling differentiation is left implicit.

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

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

Usage is implied by the description of search modes (text, type, all) and the note to override select via method_get_table_fields, but there is no explicit when-to-use or when-not-to-use guidance relative to alternatives like method_query_records.

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 disclosing the silent-failure mode (wrong/read-only field names are ignored without error), the mitigation (reply re-reads and shows stored values, so verify), and an external side effect consistent with openWorldHint: syncing accounting records to QuickBooks/Xero and converting leads into synced customers. No contradiction with destructiveHint=true — the description clarifies mutation scope rather than denying it.

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 "WRITE:" and the PATCH distinction, then layers hazards in order of importance. Dense but every clause carries risk information; the trailing endpoint path is the only mildly redundant element given the tool name.

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

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

With no output schema, the description correctly explains what the response contains (re-read stored values of the sent fields) and tells the agent to check them. For a nested-object, side-effect-bearing mutation tool, all the call-shaping information an agent needs is present.

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

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

Schema coverage is 100% and both the case-sensitivity of `fields` and the `_RecordID` integer convention are already documented in the schema, so the description largely restates them. It reinforces the silent-ignore risk rather than adding new syntax or format detail, 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?

Opens with an explicit verb+resource+scope: "WRITE: changes fields on one record" and immediately qualifies it as PATCH semantics ("only the fields you pass change"). An agent can distinguish this from method_create_record and method_get_record 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?

Gives concrete operating conditions: linked fields must be set via `_RecordID` integers, accounting records trigger a QuickBooks/Xero sync, and "There is no delete tool" implicitly bounds what this tool is for. It does not explicitly route the agent to create_record for new records or name when this should be avoided, so it stops short of full when/when-not guidance.

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