List Assets

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only — it changes nothing in Procore.' It adds useful context about the company_id default from procore_set_config and common HTTP error statuses (401, 403, 404). However, the internal contradiction about returning a single object vs. a list detracts from transparency since it misdescribes the response shape.

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 relatively compact at ~120 words and front-loads the core purpose. It covers key aspects (purpose, usage, default, safety, errors, endpoint) without excessive verbosity. However, the redundant 'Required parameters' sentence and the misleading 'single JSON object' phrase could be removed to improve clarity.

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 and a complex 22-parameter tool, the description must clarify the return structure, but it contradicts itself between 'List of Assets' and 'a single JSON object describing the asset.' It also omits pagination behavior, which is relevant given the page and per_page parameters. The error and endpoint info is helpful, but the return-type confusion is a significant gap for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds one worthwhile detail — company_id defaults to the procore_set_config value when omitted — which is not in the schema. No other parameter semantics are enriched, and the mention of 'Required parameters: company_id' is redundant 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 opening line 'Returns List of Assets by given Company' clearly states the verb, resource, and scope, distinguishing it from project-scoped siblings. However, the later sentence 'Returns a single JSON object describing the asset' directly contradicts the list return type, creating confusion about the actual purpose.

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 says 'Use this when you already know which asset you want and need its full field set,' which is misleading guidance for a list endpoint; this suggests a show/detail tool rather than a list tool. No alternatives are mentioned, and the description fails to distinguish when to use this vs. list_assets_project or show_asset_company.

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