Retrieve a specific Billy record (e.g., invoice, contact) and optionally include related resources in one call. Get exactly the data needed for accounting workflows.
Read a Billy record and optionally sideload relationships.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| include | No | ||
| resource | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only behavior (readOnlyHint, destructiveHint, idempotentHint). The description adds the optional sideloading of relationships, which is a distinct behavioral trait not present in annotations. However, it does not describe what 'sideload' means in practice, response shape, or side effects beyond the read-only nature, so added value is moderate.
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 a single sentence with no filler, front-loading the verb and object. It mentions the key optional behavior in a compact clause. Every word earns its place, making it highly concise and well-structured.
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 3 parameters, a 17-value resource enum, no output schema, and a set of sibling tools, this one-clause description is insufficient. It does not explain how to format the include parameter, what relationships are available, or what the response looks like. An agent would likely need external documentation 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 0%, so the description must compensate for explaining resource, id, and include. It only vaguely alludes to 'a Billy record' and 'relationships' without stating that include is the sideload parameter or what its valid values are. The enum lists resource options, but their semantic meaning is undocumented. An agent cannot confidently construct an include value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Read') and a resource ('a Billy record'), and adds the optional sideloading behavior. It implies fetching a single record by ID via the singular phrasing, which reasonably distinguishes it from billy_list. However, it does not explicitly name siblings or clarify that 'resource' is required to select the record type.
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 provides no guidance on when to use this tool versus alternatives. It does not reference billy_list or other siblings, nor does it state any exclusion conditions. The only usage signal is the general action 'Read,' which is insufficient for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.