Show Asset By Code

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

The description discloses several behaviors beyond the annotations: case-insensitive lookup, defaulting of company_id/project_id from procore_set_config, return of a single JSON object, and detailed error payloads (401 expired token, 403 no permission, 404 unresolved id). These complement the readOnlyHint and destructiveHint annotations without contradicting them.

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?

Every sentence in the description adds distinct value: purpose, usage context, prerequisites, return type, safety, error scenarios, required params, and API endpoint. It is front-loaded with the primary action and maintains a logical flow from selection criteria to technical details without 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?

There is no output schema, so the description appropriately states 'Returns a single JSON object describing the asset' and covers error handling. While it does not enumerate asset fields, it promises the 'full field set', which is sufficient for an agent to know what to expect. The combination of return type, error codes, and endpoint details makes it comprehensive for selection and 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?

Schema description coverage is 100%, so the baseline is 3. The description adds context about case-insensitivity, parent-record requirements, and defaulting behavior. However, it contradicts the schema's 'required' for company_id and project_id by saying they default when omitted, which could confuse an agent. Despite this, it does add value beyond the schema.

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

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

The description opens with 'Returns Asset Details by given Project & Asset Code (case-insensitive)', which clearly specifies the verb (Returns), resource (Asset Details), and distinguishing scope (by Project & Asset Code). It further differentiates from sibling tools by stating 'Use this when you already know which asset you want and need its full field set', separating it from list tools and potentially show-by-id 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?

Provides explicit when-to-use guidance: 'Use this when you already know which asset you want and need its full field set.' It also instructs to resolve asset_code with 'the matching list tool first' and explains defaulting behavior for company_id/project_id, giving the agent clear context for selection and prerequisites.

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